Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 18 Next »

TODO:

  • Channels where we receive input

  • How we choose work to be done

  • UX design

  • UI design

  • Jira

  • Sprint planning

  • …and everything else leading up to…

Development

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

We follow the development process below to have:

  • Code changes that follow the design and style of the existing code

  • Code changes that do not decrease test coverage or maintainability

  • Commit messages and Pull Requests that are in a consistent format

  • Pull Requests that are easy and fast to review

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

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

 What 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. Unless you’re the person most familiar with the area of the codebase that you are changing, first discuss the changes with that person

 Why is this important?

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. If necessary, break the Jira task into smaller pieces of work

 Why is this important?

The goal for all developers is to create Pull Requests that are easy and fast to review. If a task contains a large amount of work, break it down into smaller stand-alone tasks. Jira subtasks are one way of recording this, and allow the subtask to go through the various Jira swimlanes.

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

 List 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

 The 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

 Why 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 documentation that needs to be created or updated

  2. Periodically commit your work with messages like:

     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.
 Why this format is recommended

It’s only a recommendation that “working” commit messages use this format - these commit messages will eventually be squashed, and it’s only the final commit message that must be in this format. It’s a good idea to always use this format to be familiar with how the final commit message must look.

Tip: In the VS Code commit message input box, the up arrow allows you to scroll back through previous commit messages

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

 Everything 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 to your fork, for example by using the “Publish” button in VS Code

  2. Start to create a Pull Request for your branch, for example by using “New pull request” in the GitHub web site

  3. Enter the “title” for your Pull Request in the format feat: FORMS-1234 new map component for dropping a pin

 Why this format is mandatory

We use the format type: FORMS-NNNN description for our Pull Request titles so that:

  • the type of change is obvious from the name of the Pull Request

  • it is easy to find all Pull Requests for a given type like feat or test

  • it is easy to find the Pull Request for a given FORMS-NNNN Jira task

  • the description makes it easy to scan Pull Requests to find a change that happened

  1. Enter the GitHub “description” for your Pull Request using the template provided. The template contains comments to help make the process easier

  2. Before clicking the create button, read through all the file diffs

 Why this is recommended

This is a chance to do a self-review of your changes before creating the PR.

  • are the changes too big (too many files, too many lines) to be easily and quickly reviewed?

  • is the Pull Request doing too many different things? Can it be broken down into smaller PRs?

  • is every changed line necessary? Was anything accidentally committed?

  • are there tests to cover the code changes / additions?

  • are there documentation updates for the code changes / additions?

  1. Click the “Draft pull request” button to create the Pull Request

  2. Wait for the “Tests” GitHub Action to automatically run successfully

 What tests are run?

The “Tests” GitHub Action runs:

  • GitHub CodeQL tests to look for security issues

  • Backend Jest unit tests, including test coverage saved as an artifact

  • Frontend Jest unit tests, including test coverage saved as an artifact

Note that the test coverage is not uploaded to Code Climate, as Actions run from Pull Requests do not have access to the GitHub Secrets needed to authenticate with Code Climate.

  1. Run the deploy Action

  2. test

  3. Mark as ready for review

  4. Add reviewers

  5. Talk to reviewers

  6. Keep up to date

  7. Deploy Action

  8. merge and message

  9. Push Action

  10. Undeploy Action

  11. Code Climate / etc?

  12. Jira: moving tickets, rewrite description

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

  • No labels