Branch and Commit Naming Convention Strategy

Branch Naming Conventions

A well-defined branch naming strategy ensures clarity, collaboration, and ease of tracking development work. Below are the standardized branch prefixes to be followed:

Branch Prefixes:

• base-: Base branch for a specific module or project.

• stage-: Staging environment branch for pre-production testing.

• feature-: New feature development.

• fix-: Bug fixes.

• test-: Testing-related changes.

Branch Naming Format:

Use the Jira issue key in branch names to maintain traceability between Jira work items and development.

git checkout -b JRA-123-feature-login-improvement

Here, JRA-123 represents the Jira work item, followed by the branch type and description.

Commit Message Conventions

Adopting a structured commit message format enhances readability and helps in effective version control management. Below are the standard commit prefixes:

Commit Prefixes:

• feat: Adds or removes a new feature to the API or UI.

  • Example: git commit -m "JRA-123 feat: Implement user login API"

• fix: Fixes a bug introduced in a previous feature commit.

  • Example: git commit -m "JRA-123 fix: Correct login validation error"

• refactor: Improves code structure without changing behavior.

  • Example: git commit -m "JRA-123 refactor: Simplify authentication logic"

• perf: Performance improvements without altering behavior.

  • Example: git commit -m "JRA-123 perf: Optimize database queries"

• style: Code formatting changes (e.g., indentation, white spaces, missing semicolons).

  • Example: git commit -m "JRA-123 style: Fix indentation in user service"

• test: Adding or modifying tests.

  • Example: git commit -m "JRA-123 test: Add unit tests for login endpoint"

• docs: Documentation updates.

  • Example: git commit -m "JRA-123 docs: Update README with API usage"

• build: Changes affecting build scripts, dependencies, or CI/CD pipelines.

  • Example: git commit -m "JRA-123 build: Upgrade dependencies to latest version"

• ops: Changes related to infrastructure or deployment.

  • Example: git commit -m "JRA-123 ops: Update Kubernetes deployment configs"

• chore: Miscellaneous changes like modifying .gitignore.

  • Example: git commit -m "JRA-123 chore: Update .gitignore to exclude logs"

Linking Jira Work Items to Commits and Pull Requests

To integrate Jira with development tools like Bitbucket, GitHub, or GitLab, follow these best practices:

Branch Creation

Include the Jira work item key in the branch name.

git checkout -b JRA-123-feature-payment-integration

Commit Messages

Reference the Jira work item key at the start of commit messages.

git commit -m "JRA-123 feat: Implement payment gateway API"

Pull Requests

Include the Jira work item key in the pull request title.

JRA-123: Implement new authentication flow

Push Changes

Ensure the branch is pushed to the repository.

git push origin JRA-123-feature-login-improvement

Viewing Linked Development Information in Jira

Once changes are pushed, Jira will display development data linked to the work item.

To view linked commits, branches, or pull requests in Jira:

1. Navigate to the Jira work item.

2. Under the Development section, click the number of pull requests, branches, or commits.

3. On the Jira board, hover over development icons to see linked activities.

Automated Jira Integration Benefits:

• Ensures every commit, branch, and pull request is traceable.

• Enables seamless linking of development activities with Jira tickets.

• Provides a clear history of changes and their purpose.

Git Best Practices

Keeping a Linear Commit History

• Always ensure a linear commit history for easy debugging and review.

• Use git merge --ff-only when merging branches:

git checkout develop
git pull
git checkout some-branch-name
git pull
git merge some-branch-name --ff-only

Handling Fast-Forward Merge Conflicts

If you encounter an error like:

fatal: Not possible to fast-forward, aborting.

Follow these steps:

1. Reset to the last known good commit:

    git reset --hard 123445 // commit hash
   

2. Force push the corrected branch:

    git push origin some-branch-name --force
   

3. Cherry-pick specific commits if needed:

    git cherry-pick 123445 // commit hash
    git push origin some-branch-name
   

---

Conclusion

A consistent branch and commit naming convention simplifies code tracking, enhances collaboration, and improves CI/CD efficiency. By integrating Jira work items, developers can streamline workflows, maintain project transparency, and optimize version control management.