Versions Compared

Version Old Version 7 New Version 8
Changes made by

Walter Moar

Walter Moar

Saved on

Key

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

...

After a developer is assigned a Jira task, they begin work.

  1. Make sure that the Jira task has a good description and then move it to 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

  1. Unless you’re the person most familiar with the area of the codebase that you are changing, first discuss the changes with that person

Expand
titleWhat does this mean?

There will always be improvements underway in the CHEFS code, and any new work must align with those improvements. The end goal of these improvements is code that is:

  • necessary (YAGNI - don’t maintain, document, test, etc, code that we don’t need)

  • correct (it should work!)

  • simple (“as simple as possible but no simpler”)

  • documented

  • easy to read

  • easy to understand

  • easy to modify

  • easy to fully test

  • consistent (to reduce cognitive load)

Information that everyone should be familiar with:

  1. Using the type from Conventional Commits, decide what the primary type of work is, such as feat for a new feature

Expand
titleList of the commit `type` values that we use

  • build: change in build system or dependencies

  • ci: change in continuous integration / deployment

  • docs: change to documentation

  • feat: a new feature is being added

  • fix: an existing bug or defect is being fixed

  • perf: change to improve performance

  • refactor: change to improve code quality

  • revert: reverts changes in a previous commit

  • style: change to code style/formatting

  • test: add missing tests or correct existing tests

  1. Ensure that the main branch in your cloned fork is up to date

Expand
titleThe fetch/rebase GitHub workflow

The fetch and rebase GitHub workflow used by Kubernetes is a common way to keep cloned repos in sync with the origin and upstream repos.

Note: Some people prefer to pull and create merge commits, and that’s fine because we squash commits when a Pull Request is merged into upstream/main.

  1. With an example Jira task FORMS-1234 that is a new feat, create a branch off your main with a name like feat/1234-new-map-component

Expand
titleWhy this format is recommended

You can name the branch anything you want, but:

  • the feat/ prefix groups branches of the same type in the tools

  • the task number 1234 makes it easy to find the corresponding ticket in Jira

  1. Crank out some code and tests (or tests and code, for TDD bonus points) and whatever docs are needed

  2. Periodically commit your work with messages like:

    Code Block
     feat: FORMS-1234 description of the change
 
 This is the body of the commit message and provides more detail for anyone
 in the future who is looking into this commit.
Expand
titleWhy this format is mandatory

We want everyone to use this standard way of writing commit messages so that in the future we can use them to automatically generate a changelog.

  1. Run the unit tests using Terminal → Run Task... → Unit Tests and check the test coverage of your new code

Expand
titleEverything you ever wanted to know about the unit tests

Test coverage reports appear in:

  • Frontend: app/frontend/coverage/index.html

  • Backend: app/coverage/lcov-report/index.html

Refer to the backend unit test documentation for details on:

  • test writing strategy

  • running tests on the command line

  • running with and without the coverage report

  • running single specs or single tests

  1. Publish your branch

  2. Create a Pull Request (format, draft, read diff)

  3. GitHub Actions

  4. Do a self review (diff)

  5. (somewhere above: limit size of change)

  6. Run the deploy Action

  7. test

  8. Mark as ready for review

  9. Add reviewers

  10. Talk to reviewers

  11. Keep up to date

  12. Deploy Action

  13. merge and message

  14. Push Action

  15. Undeploy Action

  16. Code Climate / etc?

  17. Jira: moving tickets, rewrite description

What is the intention of a PR review? Ship / Show / Ask. nitpicks. style guide. choose your battles