# Best Practices & Guidelines

This guide defines the critical conventions and policies for working with IBP branches: how to name branches, write commits, run PRs and reviews, keep branches in sync, and manage environment promotions safely.

All feature branches must follow this semantic naming convention:

Release branches must use the release/ prefix. Branches without the prefix fall outside of policy.

• ✅ release/2504
• ❌ 2504 (missing prefix)

• Use lowercase kebab‑case
• Be descriptive but concise
• Avoid spaces, underscores, and special characters
• Include ticket numbers when relevant

Good Examples:

• feat/user-authentication
• fix/ibp-1234-login-issue
• docs/api-endpoints

Bad Examples:

• new_feature (use underscores)
• Fix Login (use spaces)
• feat/UserAuthentication (use camelCase)

Follow the conventional commits format: type: description

• Use imperative mood ("add feature" not "added feature")
• Keep the first line under 50 characters
• Include ticket numbers when relevant: feat: implement MFA (IBP-123)
• Add detailed description in the body if needed
• Reference related issues: Fixes #123

Good Examples:

feat: implement multi-factor authentication (IBP-123)

- Add TOTP support for user accounts
- Update login flow to require MFA
- Add MFA setup in user preferences

Bad Examples:

Added MFA  # Too vague, no type prefix
feat: Implemented multi-factor authentication for user accounts which includes TOTP support and updates to the login flow  # Too long

Create Focused Pull Requests:

• Each PR addresses a single concern
• CI checks must pass
• PR description includes what changed, how to test, and linked tickets

Never Bypass Code Review:

• All changes must be reviewed before merging
• Required reviewers must approve

Document Your Changes:

• Include a brief description in the PR
• Reference related tickets or requirements
• Include how you tested your change
• Suggest how the reviewer should test

For Authors:

• Code follows team conventions
• Tests are included and passing
• Documentation is updated if needed
• PR description is clear and complete
• Related tickets are linked

For Reviewers:

• Code logic is correct
• Security implications are considered
• Performance impact is acceptable
• Tests adequately cover the changes
• Documentation is accurate

Developers:

• Regularly merge the current release branch into your feature branch
• Resolve conflicts early

Team Leads:

• Merge completed features into the release branch only when stable
• Ensure release branches stay up to date
• Coordinate with other teams on shared changes

Prevention:

• Regularly sync with parent branches to minimize conflicts
• Communicate with team members about overlapping changes
• Use feature flags to avoid conflicts in shared code

Resolution:

• Resolve conflicts in your feature branch before creating a PR
• Test thoroughly after resolving conflicts
• Get additional review if conflicts were complex

• Test thoroughly in dev before promoting to higher environments
• Use feature flags for gradual rollouts when possible
• Monitor deployments and be ready to rollback if needed

Do not commit directly to environment branches (dev, qa, preprod1, pent, prod1). All environment promotions must happen via pull requests with documented testing. Hotfixes included

• All automated tests pass
• Code review approved
• Security scan passes
• Performance tests pass (if applicable)
• Documentation updated

• Feature tested in dev environment
• Integration tests pass
• Deployment plan documented
• Rollback plan prepared
• Stakeholders notified

• Clearly communicate when release branches are locked
• Notify teams of hotfix deployments
• Document any deviations from standard process

• Escalate blocking issues promptly
• Document workarounds and temporary solutions
• Schedule follow-up reviews for emergency fixes

• Git for version control
• Azure DevOps for pull requests and CI/CD
• Branch policies for automated validation

• Automated testing on every PR
• Automated deployment to dev environment
• Automated security and quality scans
• Automated branch protection policies