✍️ GitHub Conventions for 01-Edu

This guide lists the GitHub rules for the 01-Edu organization. The rules apply to every repository, and they cover commit messages, pull requests and issues.

📑 Table of Contents

• Commit Messages
• Pull Requests
• Issues

💬 Commit Messages

Format

Write each commit message in this format:

type(scope): description

The format follows the Conventional Commits v1.0.0 standard, and it has three parts:

• type: the category of the change.
• scope: the part of the codebase that changes.
• description: a short description of the change, written in the imperative.

Use lowercase letters in the type and the scope, and use one word for the scope.

Types

Use one of the Conventional Commits types:

Type	Use for
feat	A new feature
fix	A bug fix
docs	Documentation
style	Formatting only
refactor	A change that adds no feature and fixes no bug
perf	A performance improvement
test	Adding or changing tests
build	The build system
ci	Workflows and pipelines
chore	Maintenance tasks
revert	A revert of an earlier commit

The compliance workflow also accepts add, delete, update, bump and security.

Examples

feat(api): add user export endpoint
fix(db): expire audit only if user is anonymised
docs(readme): rewrite the setup guide
refactor(static): split the layout component
ci(workflow): run shellcheck on pull requests

Breaking Changes

Add ! after the scope to mark a breaking change, as in the Conventional Commits example:

fix(api)!: update package version from v6 to v8

🔄 Pull Requests

Title Format

Start every pull request title with a ticket reference:

TAG-#### Pull request title

• TAG is the project identifier, for example DEV, CON or TNT.
• #### is the ticket number.
• title is a short description of the change.

Examples

DEV-1234 Update user data should not expire audits, only in anonymised
CON-1234 Create subject, audit, and refs for matrix-factorization
TNT-1234 Create Database Schema (draft)
DEV-1234 | SUP-1234 Git hard reset feature missing for admin audits model

Requirements

1. Body Content

   • Start the body with the TAG-#### reference.
   • Describe the change. You can copy the description from the ticket.
   • List breaking changes. You can copy them from the ticket.

2. Special Tags

   • Mark external contributions with [EXTERNAL].
   • Mark invalid pull requests with [INVALID].

3. Required Metadata

   • Add a team label, such as content, platform or tournament.
   • Add context labels, such as breaking or trivial.
   • Assign at least one reviewer.
   • Assign at least one assignee.

4. Code Quality Format the code with the right tool:

   • General: Prettier
   • Shell scripts: ShellCheck
   • JavaScript and TypeScript: Biome
   • Python: Black

Handling Spam PRs

Use this template for spam or unauthorised pull requests:

> [!WARNING]
>
> ## BLOCKED: @<username>
>
> This user has been blocked:
>
> - Rogue contribution / SPAM

Example:

01-edu/public#2722

❓ Issues

External Contributor Guidelines

Start the title of an external issue with a type prefix:

• [QUESTION]: a question about implementation or requirements.
• [BUG]: a bug or unexpected behaviour.
• [FEATURE]: a new feature or improvement.

Examples

[QUESTION] The emotions-detector subject requirements reasonable?
[BUG] Possible issue in NascarOnlineAlpha gaming project
[FEATURE] Add deep-in-system audit details

Issue Requirements

1. Labels

   • Add the Bug label to a bug report, and add a severity label when needed.
   • Add the Feature label to a feature request.
   • Add the Question label to a question.

2. Content

   • Describe the issue.
   • List the steps that reproduce the bug.
   • Show the expected result and the actual result.
   • Add screenshots or logs.
   • Add environment details when they matter.

Closing Invalid Issues

Use this template when an issue lacks information or the author does not respond:

> [!IMPORTANT]
>
> ## @<username>: This issue has been closed due to lack of context/clarity/substance/responsiveness!
>
> If you find there is something wrong with a subject/exercise/feature, please feel free to open a new issue with an appropriate title, context and further details that would help our team to address the issue effectively.
>
> We require the following information:
>
> - The issue/error you are encountering from the platform
> - The solution you're trying to submit / steps to reproduce the issue/error
> - The screenshot of the issue/error
> - Any additional details

Example:

01-edu/public#2759