Git Guide

Guidelines for using Git, including branch and commit naming conventions.

Branch Naming Conventions

To keep our repository organized, we follow a strict naming convention for branches. This helps in identifying the purpose of a branch at a glance. The format is `type/short-description`.

# Branch types:
# feature: For developing a new feature.
# bugfix: For fixing a bug.
# hotfix: For making urgent fixes in production.
# release: For preparing a new release.
# docs: For writing or updating documentation.
# refactor: For refactoring code without changing functionality.
# test: For adding or improving tests.
# build: For changes related to the build system.
# ci: For changes related to Continuous Integration.

# Examples:
feature/add-user-authentication
bugfix/fix-login-button-bug
hotfix/critical-security-patch
release/v1.2.0
docs/update-readme
Commit Naming Conventions

Clear and concise commit messages are crucial for understanding the history of the project. We follow the Conventional Commits specification. The basic format is `<type>: <description>`.

| Type     | Title            | Description                                                     |
|----------|------------------|-----------------------------------------------------------------|
| feat     | Features         | A new feature for the user.                                     |
| fix      | Bug Fixes        | A bug fix for the user.                                         |
| docs     | Documentation    | Changes to the documentation.                                   |
| style    | Styles           | Changes that do not affect the meaning of the code.             |
| refactor | Code Refactoring | A code change that neither fixes a bug nor adds a feature.      |
| test     | Tests            | Adding missing tests or correcting existing tests.              |
| chore    | Chores           | Changes to the build process or auxiliary tools.                |
| build    | Build System     | Changes that affect the build system or external dependencies.  |
| ci       | CI/CD            | Changes to our CI configuration files and scripts.              |
Basic Git Workflow

Follow these steps for a typical development cycle. This workflow ensures that your work is isolated and can be reviewed before being merged into the main branch.

# 1. Update your main branch
git checkout main
git pull origin main

# 2. Create a new feature branch
git checkout -b feature/your-feature-name

# 3. Make your changes and commit them
# ...do your work...
git add .
git commit -m "feat: implement the new feature"

# 4. Push your branch to the remote repository
git push origin feature/your-feature-name

# 5. Open a Pull Request on the repository platform (e.g., GitHub, GitLab).
Pull Request Best Practices

Pull Requests are fundamental to our collaboration process. A good PR is easy to review and understand. Keep your PRs small and focused on a single task. Provide a clear title and description that explains the 'what' and 'why' of your changes. If your PR addresses an issue, link to it. Always review your own changes before requesting a review from others.

Resolving Merge Conflicts

Merge conflicts happen when Git is unable to automatically resolve differences in code between two commits. When this occurs, Git will mark the files with the conflict. You need to manually edit the conflicted files to resolve the differences, then add the resolved files and commit them to finalize the merge.

# 1. Identify the files with conflicts (e.g., via 'git status').
# 2. Open the conflicted file. You'll see markers like:
<<<<<<< HEAD
// Code from your current branch
=======
// Code from the branch you are merging
>>>>>>> other-branch-name

# 3. Edit the file to keep the desired changes and remove the conflict markers.
# 4. Stage the resolved file.
git add <resolved-file-name>

# 5. Continue the merge or commit the changes.
git commit -m "fix: resolve merge conflict"