Immortal Handbook

Appearance

Git Practices ​

So you're eager to get started with your project, that's great, but before you commit your first line of code, let's take a moment to understand some essential Git practices that will help you and your team collaborate effectively.

Table of Contents ​

Framework ​

We're using Git as our version control system, and we follow the GitFlow Workflow for our branching strategy. This means we have specific branches for development, features, releases, and hotfixes.

Branching Strategy ​

Here's a quick overview of our branching strategy:

Default Branch ​

We use master as our default branch, which always contains the latest stable release.

You won't be committing directly to master. Instead, you'll create feature branches for your work.

Development Branch ​

The develop branch is where all the feature branches are merged once they are complete and tested. This branch contains the latest development changes that are ready for the next release.

Feature Branches ​

Feature branches are created from the develop branch and are used for developing new features or making changes. The naming convention for feature branches is feat/your-feature-name.

Hotfix Branches ​

Hotfix branches are created from the master branch to quickly address critical issues in the production code. The naming convention for hotfix branches is hotfix/your-hotfix-name.

Branch Naming Convention ​

Use branch prefixes based on the type of work:

  • feat/<short-description> for new functionality.
  • fix/<short-description> for bug fixes.
  • docs/<short-description> for documentation-only updates.
  • chore/<short-description> for maintenance/tooling tasks.
  • hotfix/<short-description> for urgent production fixes.

Once you've completed your work on a feature or hotfix branch, you'll create a pull request to merge your changes back into the master and develop branches.

Commit Messages ​

Writing clear and concise commit messages is crucial for maintaining a clean project history.

Here are some guidelines for writing good commit messages:

  • Follow Conventional Commits: <type>(<scope>): <description>.
  • Keep the subject line concise (preferably <= 72 characters).
  • Use lowercase type values such as feat, fix, docs, refactor, chore, ci.
  • Clearly explain what changed and why. Avoid vague messages like "Fix stuff" or "Update code."
  • Focus on the intent of the change, not just the mechanics.

Conventional Commit Format ​

Use a clear type and optional scope:

type(scope): short description

Examples:

feat(auth): add JWT-based login endpoint
fix(session): prevent timeout on refresh
docs(readme): add local setup steps
docs(onboarding): clarify first-day checklist
chore(deps): update Vue to latest compatible version
chore(repo): clean up obsolete handbook assets

Provide Context ​

Provide context, reasoning, or details for the change.

Use bullet points or paragraphs for clarity, and wrap lines at ~72 characters for readability in tools like Git.

feat(auth): add user authentication endpoint

- Implement JWT-based authentication for API
- Add middleware for token validation
- Update README with setup instructions

Include Metadata ​

We use Plane for tracking issues and tasks. Add task metadata in the commit footer:

feat(auth): add user authentication endpoint

Refs: T123

If the task is completed in that commit, use:

fix(auth): handle expired refresh token

Done: T123

Avoid Generic Messages ​

Avoid generic messages like "Fix stuff" or "Update code." Be specific about what was changed and why.

Messages like "WIP," "Fix," or "Changes" are unhelpful. Instead, specify the change (e.g., "Fix null pointer exception in user service").

Examples of Good and Bad Commit Messages ​

Good Examples:

feat(auth): implement user authentication
docs(onboarding): add attendance instructions
fix(auth): resolve session timeout in login flow
- Resolve issue with session timeout
- Add unit tests for login functionality
docs(readme): update installation instructions
- Add steps for setting up the development environment
- Include troubleshooting tips
docs(remote-company): refine communication policy wording
refactor(user-service): simplify dependency wiring
- Improve code readability and maintainability
- Remove deprecated methods
- Add comments for complex logic
ci(gitlab): run docs build in staging pipeline
chore(deps): bump vitepress plugin versions
chore(repo): remove legacy deployment notes

Bad Examples:

update auth
fix bug
changes

Use The Right Verb ​

Use the right Conventional Commit type to describe intent:

  • feat: new functionality (e.g., feat(profile): add user profile page)
  • fix: bug fix (e.g., fix(auth): prevent crash in login flow)
  • docs: documentation-only changes
  • refactor: code changes without behavior change
  • ci: CI/CD pipeline changes
  • chore: maintenance tasks (dependencies, tooling, cleanup)
  • revert: undo a previous commit

Pull Requests ​

Once you've completed your work on a feature or hotfix branch, it's time to create a pull request (PR) to merge your changes back into the develop and master branches.

If your PR addresses a specific Plane task, make sure to include the task ID in the PR title or description using the format T[task_id].

The feat/* branch should be merged into develop, and the hotfix branch should be merged into both master and develop.

Creating a Pull Request ​

  1. Push your feat/*, fix/*, docs/*, chore/*, or hotfix/* branch to the remote repository.
  2. Navigate to the repository on GitLab.
  3. Click on "Merge Requests" in the sidebar.
  4. Click on "New Merge Request."
  5. Select your source branch (feat/*, fix/*, docs/*, chore/*, or hotfix/*) and target branch (develop/master).
  6. Fill in the PR title and description, including any relevant Plane task IDs.
  7. Assign reviewers and set labels if necessary.

Code Reviews ​

Code reviews are an essential part of our development process. They help ensure code quality, share knowledge, and catch potential issues early.

Review Process ​

  1. Once a PR is created, assign at least one team member as a reviewer.
  2. Reviewers should thoroughly examine the code changes, checking for functionality, readability, and adherence to coding standards.
  3. Leave comments or suggestions for improvements directly on the PR.
  4. The author should address any feedback and make necessary changes.
  5. Once the reviewer is satisfied, they can approve the PR.
  6. The PR can then be merged into the target branch.

Review Guidelines ​

  • Be respectful and constructive in your feedback.
  • Focus on the code, not the person.
  • Ask questions if something is unclear.
  • Suggest improvements, but also acknowledge good practices.
  • Ensure that the code adheres to our coding standards and best practices.
  • Verify that the code is well-tested and that tests pass.
  • Check for potential performance issues or security vulnerabilities.
  • Ensure that the commit messages are clear and follow our guidelines.

Merging ​

Once a PR has been approved, it's time to merge the changes into the target branch.

Merging Process ​

  1. Ensure that the target branch is up to date with the latest changes.
  2. If there are any conflicts, resolve them before merging.
  3. Use the "Merge" button on the PR page to merge the changes.
  4. After merging, delete the feature or hotfix branch to keep the repository clean.
  5. If the PR was for a hotfix, ensure that the changes are also merged into the develop branch.

Merge Strategies ​

For master branch merges, we use "Squash and Merge" to keep the commit history clean. This combines all commits from the feat/* branch into a single commit on the target branch.

For develop branch merges, we use "Merge Commit" to preserve the full history of changes. This allows us to see the individual commits made during feature development.

Conflict Resolution ​

Conflicts can occur when multiple people are working on the same codebase. Here's how to handle them:

  1. If you encounter a conflict while merging, Git will notify you of the files that are in conflict.
  2. Open the conflicting files and look for the conflict markers (<<<<<<<, =======, >>>>>>>).
  3. Manually resolve the conflicts by choosing which changes to keep or combining them as necessary.
  4. After resolving the conflicts, stage the changes using git add <file>.
  5. Commit the resolved changes with a clear message indicating that conflicts were resolved.
  6. Push the changes to the remote repository and update the PR if necessary.
  7. Notify the reviewers that the conflicts have been resolved and the PR is ready for review again.

Best Practices ​

  • Regularly pull changes from the develop branch to keep your feat/* branch up to date.
  • Write clear and concise commit messages.
  • Create small, focused PRs that are easy to review.
  • Always request a code review before merging.
  • Address feedback promptly and professionally.
  • Keep your branches organized and delete them after merging.
  • Use Plane task IDs in commit footers and PRs to link work to specific tasks.
  • Test your code thoroughly before creating a PR.
  • Follow coding standards and best practices to maintain code quality.

Contributors

The avatar of contributor named as Pezhvak Pezhvak

Changelog