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.
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
Once changes are pushed, Jira will display development data linked to the work item.
To view linked commits, branches, or pull requests in Jira:
Navigate to the Jira work item.
Under the Development section, click the number of pull requests, branches, or commits.
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
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:
Reset to the last known good commit:
git reset --hard 123445
Force push the corrected branch:
git push origin some-branch-name --force
Cherry-pick specific commits if needed:
git cherry-pick 123445
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.
