Development Workflow - acolorbright/handbook GitHub Wiki

Step 1: Working on issues

  • Pick an available issue according to priority and assign it to yourself.
  • Ensure you understand exactly what is required to consider the issue “done”.
  • Move the issue into the appropriate column (e.g. "In Progress") on the project board to make clear that it is being currently worked on.
  • Locally, ensure main is up-to-date and then create a new branch off it beginning with the issue number and then keywords related to the issue separated by dashes, e.g. git checkout -b 402-search
  • Make commits locally using semantic commit messages.
  • Keep the branch up-to-date with main either by periodically merging (git merge main) or rebasing (git rebase main). Rebasing is preferred, as it limits the noise created by merge commits, but not required.
  • If appropriate, make any corresponding updates to the documentation in the README.
  • Push your commits to the same branch on the origin remote, e.g. git push origin 402-search
  • Ensure that your code addresses everything required to consider the issue “done”.
  • Create a pull request from your branch against main. Include "Closes #[issue number]" in the description to link the PR to the issue.
  • If the PR is not immediately ready for review, add [WIP] to the start of the name. Otherwise, request a review from a team member using GitHub's "Reviewer" column and move the issue into the QA column to show that it is awaiting QA.

Step 2: Code review

  • Bear in mind The 10 Commandments of Navigating Code Reviews.
  • Verify that continuous integration passes.
  • Verify that the deploy preview / review app builds and runs.
  • Verify that the changes address everything described in the issue, whether fixing a bug or providing an enhancement.
  • Verify that the changes don't break existing functionality (this is more difficult and part of why tests are important).
  • Examine the code for readability, understandability, accuracy and efficiency.
  • Comment on areas for improvement (or praise solutions) at their location in the code. Do not update the PR directly.
  • Give a final review either as Approve (if approved for merging) or as Request for Changes (if there are blocking issues) or as Comment (if not yet approved).

Step 3: Response to code review and merging changes

  • Bear in mind The 10 Commandments of Navigating Code Reviews.
  • Address or discuss any requests for clarification or changes.
  • Notify the reviewer that the PR has been updated.
  • Wait for another review.
  • Once approved, merge the PR.
  • If appropriate, make any corresponding updates to the documentation in the project wiki.