Git Etiquette

Author: Gary Johnson

Date: 2022-02-09

Not everyone on the team uses the GitHub web interface for reviewing, commenting on, and merging PRs. For this reason, we have used a Mattermost-based conversational workflow for moving PRs forward thus far.

The process currently works as follows:

1. Alice pulls the latest development branch for their repository.

2. Alice creates a feature branch off of development called alice-brief-feature-description (where brief-feature-description is determined by what is being worked on in this branch).

3. Alice works on their feature branch locally, applying commits as necessary until the changeset is complete.

4. Alice pushes the alice-brief-feature-description branch to GitHub/GitLab.

5. Alice creates a PR/MR to merge alice-brief-feature-description into development.

6. Alice makes an announcement on the Mattermost channel for the relevant project like "Opened PR45 (PYR-230 Jira issue summary or Feature branch description) "

7. Bob (who is working on the same project as Alice) reviews PR45 and provides comments on GitHub/GitLab.

8. Bob makes an announcement on the Mattermost channel for the project like "Comments added to PR45 (PYR-230 Jira issue summary or Feature branch description)"

9. Alice makes the requested changes on alice-brief-feature-description and pushes the new commits to GitHub/GitLab.

10. Alice makes an announcement on the Mattermost channel for the project like "Updated PR45 (PYR-230 Jira issue summary or Feature branch description)"

11. Bob re-reviews the latest changes from Alice and may submit another round of comments on GitHub/GitLab.

12a. If Bob has submitted additional comments, Bob makes an announcement on the Mattermost channel for the project like "Comments added to PR45 (PYR-230 Jira issue summary or Feature branch description)"

12b. If Bob has no further comments, Bob merges alice-brief-feature-description into development (closing the PR and deleting the branch) and makes an announcement on the Mattermost channel for the project like "Merged PR45 (PYR-230 Jira issue summary or Feature branch description)."

13. Alice resumes from step 1.

Other things to note:

• PR merging is done by the project lead upon approval of the changeset to ensure that the author does not make unreviewed changes prior to a merge. This also ensures that one person is tracking that things are reviewed and merged in the correct order.
• Our Jira instance is set up to recognize smart commits and progress issues accordingly. You should place the ticket number (e.g., PYR-230) at the beginning of your PR description or in your last commit on the branch. Generally putting it in the PR description is preferred.
• When merging a PR with multiple commits, you should use the "Squash and merge" option in the GitHub web UI. When merging a PR with just one commit, you can use the default "Merge pull request" option.