Skip to content

Update CONTRIBUTING.md #524

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 71 additions & 0 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,3 +27,74 @@ __Some things that will increase the chance that your pull request is accepted__

* Follow our [coding style guide](../docs/CODE_OF_CONDUCT.md).
* Write a good commit message.

# Branch Naming Conventions
The structure and design conventions are based mainly on the “Conventional Branch” concept and the team’s current work process.

## Purpose
1. Purpose-driven Branch Names: Each branch name clearly indicates its purpose, making it easy for all developers to understand what the branch is for.
2. Integration with CI/CD: By using consistent branch names, it can help automated systems (like Continuous Integration/Continuous Deployment pipelines) to trigger specific actions based on the branch type.
3. Better type and version control: Branches are related to a specific type of change in the code and the version that is being worked on, allowing for a much better backtracking.

## Basic Rules
- Naming structure:
`<type>/<description>`
- Naming prefixes (Types):
- feature/: For new features (e.g., feature/add-login-page).
- fix/: For general fixes or code correcting.
- update/: For code upgrade or non-breaking code refactoring.
- chore/: For non-code tasks like dependency, docs updates (e.g., chore/update-dependencies).
- release/: For branches preparing a release (e.g., release/v1.2.0).
- Use Lowercase Alphanumeric and Hyphens: Always use lowercase letters (a-z), numbers (0-9), and hyphens to separate words. Avoid special characters, underscores, or spaces.
- No Consecutive or Trailing Hyphens: Ensure that hyphens are used singly, with no consecutive hyphens (feature/new--login) or at the end (feature/new-login-).
- Keep It Clear and Concise: The branch name should be descriptive yet concise, clearly indicating the purpose of the work.
- Include Ticket Numbers: If applicable, include the ticket number from your project management tool to make tracking easier. For example, for a ticket issue-123, the branch name could be feature/issue-123-new-login.

## General Project Structure
```
main
├── release/v1.x.x
│ ├── feature/lorem-ipsum
│ └── fix/ipsum-dolor
├── release/v2.x.x
│ └── chore/dolor-sit
└── release/v3.x.x
├── update/sit-amet
├── feature/amet-consectetur
└── chore/consectetur-adipiscing
```
- main: This branch should only contain working versions completely tested and only receive pull requests from finalized release branches. All new release/ branches must come from this one.
- release: The creation of these branches should be done from the last version of main when created. Only this branches can make pull requests to main.
- Other branches: All working branches should come from a release branch. These are the only ones that should receive direct commits from changes made by development staff. These branches should only do PR to the active release branch.

# Commits Naming Conventions
The structure and design conventions are based mainly on the “Conventional Branch” concept and the team’s current work process.

## Purpose
1. Automatically generating CHANGELOGs: When the commits are concise, and precise changelogs can be automated or semi-automated from the commit history.
2. Communicating the nature of changes to everyone: Being able to understand the type of changing by just looking at a name and understanding the basics of a commit just by the title is useful in analysis and backtrack situations.
3. Building code habits and good practices: Maintaining structured commits also leads to more precise coding practices and coherent code changes.

## Basic Rules
- Naming structure:
```
<type>: <description>

[optional body]
```
- Naming prefixes (Types):
- fix: A commit of the type fix patches a bug in your codebase.
- feat: A commit of the type feat introduces a new feature to the codebase
- <type>!: A commit that appends a ! after the type introduces a breaking change. A breaking change can be part of commits of any type.
- update: A commit of type update changes existing code or refactors functions without changing functionality of adding features in your codebase.
- build: A commit of type build changes build process in your codebase.
- docs: A commit of type docs is for creation or updating documentation in your codebase.
- chore: A commit of type chore is for every other minor task in your codebase.
- Commits must be prefixed with a type, which consists of a noun, feat, fix, etc., followed by the optional !, and required terminal colon and space.
- A description must immediately follow the colon and space after the type prefix. The description is a short summary of the code changes, e.g., fix: array parsing issue when multiple spaces were contained in string.
- A longer commit body may be provided after the short description, providing additional contextual information about the code changes. The body must begin one blank line after the description.
- A commit body is free-form and may consist of any number of newline separated paragraphs.

# Bibliography
[1] “Conventional Branch,” Conventional Branch, 2025. https://conventional-branch.github.io/ (accessed 2025).</br>
[2] “Conventional Commits,” Conventional Commits. https://www.conventionalcommits.org/en/v1.0.0/ (accessed 2025).
Loading