git-guidelines.md

Git Workflow Guidelines

Branching

Branch names should:

1. Follow git-flow style, i.e. story branches begin with feature/, bugs with bugfix/, etc.
2. Contain the JIRA ticket ID (if one exists) at the beginning of the branch name (but after the git-flow label)
3. Have a descriptive name. For the example ticket with title "As an admin user, I want to see all widgets on my dashboard" consider the following example/counter example:
   • Bad: feature/ABC-123-as-an-admin-user-i-want-to-see (you want to see what???)
   • Good: feature/ABC-123-show-all-widgets-to-admins
4. Be as short and concise as possible while following the other guidelines

Commits

Commit Messages

This page is a great reference for the structure of good commit messages. Include the JIRA ticket number somewhere (if applicable). Preferably, this should go at the end of the commit message (as shown in some of the examples) since the primary purpose of it's inclusion is to link JIRA tickets to commit history in Stash.

Here's a commit-msg hook that can be used to validate most of these requirements.

Pull Requests

Pull Request Titles

Pull request titles should follow the same guidelines as commit subject lines. The Stash inbox view has limited space and only shows ~40 characters:

Pull Request Descriptions

Pull request descriptions should include any relevant information required to test the code. This may include:

• Setup instructions and requirements
• Links to other pull requests to test with simultaneously
• Test procedure

Pull request descriptions should not include a list of commits since there is already a "Commits" tab which shows the list of commits on the branch.

Pull Request Comments

Pull request comments should be placed in the "Diff" tab if they concern specific pieces of code. This ensures that:

• Comments are hidden from the diff when the source is updated to correct the comment.
• Comments show up in the main "Overview" tab for the pull request. Comments on individual commits will not show up in this view.

The pull request author should create tasks on comments where corrections are to be made. If the author feels that no action is required, they should leave an explanatory comment in reply.

Declining/Approving Pull Requests

A pull request should be declined when:

1. Above guidelines are clearly not met
2. A reviewer discovers an issue or issues with the proposed change that should be resolved before further review is attempted.

When declining a PR, be sure to leave an explanatory comment.

Pull requests should remain open when discussing proposed changes. Once the author has made any requested changes, they may @mention reviewers to signal that the PR is ready to be re-reviewed.

A pull request may be accepted when:

1. Reviewer has completed the test procedure explained in the description and verified the results match the expected behavior.
2. All tasks have been marked complete
3. Bamboo builds are passing

The project repo should have the Workzone plugin configured to prevent merging unless those conditions are met.

Git Hooks

It is advisable to use Git's hook system to automatically validate your commits. For example, a pre-commit hook can be used to verify that your code meets style guidelines or passes the test suite before being committed. This prevents cluttering of the history with broken code and fixup commits.

A commit-msg hook can verify that your commit messages match the recommended guidelines.

See the Git hooks documentation for more details on what hooks are available and what they do.