2. Source Control and Git Branch Naming Conventions

This document outlines our team's git branch naming conventions to maintain a clean and organized repository. Following these conventions helps everyone understand the purpose of each branch and its relationship to specific issues.

2.1. Branch name convention

Every branch name must contains 3 parts as described bellow:

1. Type prefix
2. Issue number (#)
3. Brief description

Branch Type Prefixes

to indicate the purpose of your branch add one of the categories bellow as a prefix.

Prefix	Purpose
feature/	New features or enhancements
bugfix/	Bug fixes
docs/	Documentation updates
test/	Adding or updating tests
refactor/	Code refactoring without changing functionality
chore/	Maintenance tasks, dependency updates, etc.

Issue Number

Ideally, every branch should be associated to a GitHub issue number prefixed with # to maintain traceability between branches and issues:

Brief Description

Also, a brief description using underscores to separate words should be added as branch name suffix. The description should be concise, but descriptive enough to understand the branch's purpose:

docs/#15_api_authentication_docs

2.2. Creating a New Branch

To create a new branch follow these steps:

# First, ensure you're on the main branch and up to date
git switch main # git checkout main

# Next, synchronize the local branch with remote branch
git pull

# And finnaly, create and switch to the new branch
git switch -c docs/#22_getting_started_tutorial

A few examples of branch names:

# For a new feature related to issue #42
git switch -c feature/#42_user_authentication

# For a bug fix related to issue #27
git switch -c bugfix/#27_fix_login_error

# For documentation updates related to issue #12
git switch -c docs/#12_readme_documentation

# For refactoring related to issue #35
git switch -c refactor/#35_optimize_database_queries

Best Practices

1. Keep branches focused: Each branch should address a single issue or feature.
2. Regular updates: Frequently merge or rebase with the main branch to stay up to date.
3. Delete after merging: Clean up branches after they've been merged to keep the repository tidy.
4. Descriptive names: Ensure branch names clearly communicate purpose to other team members.

Branch Lifecycle

1. Create a branch from main for your task
2. Make your changes with descriptive commits
3. Push your branch to GitHub
4. Create a Pull Request
5. After review and approval, merge to main
6. Delete the branch once merged

By following these conventions, we maintain a clean repository history and make collaboration easier for everyone on the team.