Versions Compared

Version Old Version 19 New Version 20
Changes made by

Walter Moar

Walter Moar

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  1. Make sure that the Jira task has a clear description, and then move it to In Progress IN PROGRESS

Expand
titleWhat makes a good Jira description

Ideally the description in the Jira task is written in a way that it can be copied and pasted as the description of the Pull Request. This is very subjective, but the description should:

  • Clearly describe the change that is needed

  • Be written in plain language - if it’s very technical then perhaps add a “Background” introduction that explains things in plain language

  • Contain an “Acceptance Criteria” section detailing what is needed for the task to be considered done

...

  1. Crank out some code and tests (or tests and code, for TDD bonus points) and whatever documentation that needs to be created or updated

  2. Periodically commit your work with messages like:

    Code Block
     feat: FORMS-1234 new map component for dropping a pin
 
 Added a new map component that allows the user to drop a "pin" on the map,

and the location is saved as both Lat/Lon or UTM coordinates.

...

  1. Using your Pull Request number, run the “PR Deploy” Action

Expand
titleHow do I know when the changes are deployed?

There are various ways to tell this:

  • Watching the Action you will see the Deploy step complete and display the URL of the deployment

  • Unless you have the notifications disabled, you should receive an email

  • The Action will add a comment to the PR that contains the URL of the deployment

  1. Test your changes in the deployed PR

...

  1. instance

  2. Do a self-review of your Pull Request

Expand
titleWhy is a self-review needed?

Pull Requests should be created so that can be easily and quickly reviewed. By reading through every line of your code changes (because the reviewer should also be reading every line) you check that the Pull Request will make sense to your reviewers. It might help to add a GitHub comment to your code changes to explain them better. It might help to split your Pull Request into smaller pieces if it is too large: small Pull Requests that take five or ten minutes to review will get a more thorough review than Pull Requests that take hours or days.

...

Expand
titleIf necessary?!!

Ideally every developer would review and understand every change in every Pull Request, but that’s not practical. Code reviews have many purposes:

  • Sharing knowledge: more people understanding the changes means better group knowledge of the code

  • Enforcing consistency: the code should look like a team effort, not a dozen people doing things their own way - this reduces cognitive load when working with the code

  • Preventing bugs: the goal of a review is not to test that someone’s code works, that’s the developer’s job. Reviewers very familiar with the code being changed, though, are likely to catch bugs introduced by people less familiar with the code - this is a great learning opportunity.

There are two ways of looking at Pull Requests:

  1. Those that use existing concepts / designs vs. those that introduce new concepts / designs

  2. Those that are simple changes vs. those that are complex changes

We can use the Ship / Show / Ask approach to changesPull Requests:

  • Existing concepts / designs + simple changes: Ship it (example: dependency update, typo fix, small bug). Show or Ask for a review if you are uncertain or otherwise feel it’s necessary

  • Existing concepts / designs + complex changes: Show / tell other developers about the changes but doesn’t necessarily need a review (example: new feature that’s very similar to existing features). Ask for a review if you are uncertain or otherwise feel it’s necessary

  • New concepts / designs + simple changes: Ask for a review (example: small bugfix that needs a big refactoringnew way of doing things)

  • New concepts / designs + complex changes: Ask for a review (example: new feature that’s different from anything we have)

  1. Talk to reviewers

  2. Keep up to date

  3. Deploy Action

  4. merge and message

  5. Push Action

  6. Undeploy Action

  7. Code Climate / etc?

  8. Jira: moving tickets, rewrite description

...

  1. Tell your reviewers about the Pull Request

Expand
titleIs this always needed?

This step really depends on the reviewer. Some people notice that they have been asked to do a review, but many do not. It doesn’t hurt to post in the team channel on Discord that something is ready for review and “mention” the reviewers.

  1. In Jira move the task to PULL REQUEST (PR)

  2. Keep your branch up to date with main

Expand
titleHow often should I update?

It depends! It’s good to always be up to date because the testing and review is more meaningful if the base branch is up to date. However, it can also waste a lot of time if one person is putting in multiple small changes and everyone is trying to keep up. Find a balance between having a current base and spending time keeping it current.

  1. Re-run the “PR Deploy” Action after updating your branch

Expand
titleIs this necessary?

If you or others are testing the deployed code, but the code is not up to date with main, then bugs could sneak through. When you look at your PR there will be comments in the timeline for commits, and comments from the PR Deploy Action. If there are commits after the last PR Deploy, then it should be deployed again. Retesting might be wanted if there were merge conflicts or other contention between the new main and the PR code.

  1. Wait for approval (if needed) and merge your changes with the properly formatted commit message like:

Code Block
feat: FORMS-1234 new map component for dropping a pin
 
Added a new map component that allows the user to drop a "pin" on the map,
and the location is saved as both Lat/Lon or UTM coordinates.
Expand
titleWhy is this format mandatory?

This format must be followed as we eventually want to introduce automated changelogs and versioning.

  1. Monitor the Push Action

Expand
titleWhat does this Action do?

The Push Action runs on merge, and:

  1. Build the application

  2. Deploys the application to dev

  3. Waits for gatekeeper approval to deploy to test

  4. Deploys the application to test

  5. Waits for gatekeeper approval to deploy to prod

  6. Deploys the application to prod

Once you have merged your changes, ensure that they are deployed through all environments. Do not leave a deployment “hanging” and deployed to only the lower environments, as the next merge will probably cause it to go all the way to prod. If the change is tested and approved, it must go to prod.

  1. Run the PR Undeploy Action with your Pull Request number

Expand
titleCan this be automated?

Maybe? Merge can only be done by people with write access to the repo, so in theory on merge we would have access to the GitHub secrets and could undeploy automatically if we can figure out the PR number.

  1. Check Code Climate

Expand
titleWhat's Code Climate?

We use Code Climate to monitor maintainability and code coverage. However, it will probably be replaced by SonarCloud in the near future. But it doesn’t hurt to check that your changes didn’t decrease our maintainability or code coverage.

  1. Move Jira task to DONE