/
Path to Production

Path to Production

Owned by Walter Moar
Last updated: Sept 18, 2024
9 min read

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

We follow the development process below to have:

  • Code changes that maintain the existing code’s design and style

  • 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 to avoid review bottlenecks

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

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” section 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

This is important because you don’t want to spend time on a Pull Request only to find out that it has to be completely redone because of its core design. Also, there will always be improvements underway in the CHEFS code, and any new work must align with those improvements - so following the existing design/code might not be the best approach. 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

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 Kanban stages.

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

  • 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 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

  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 either Lat/Lon or UTM coordinates.

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

  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

  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

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

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

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

  1. Test your changes in the deployed Pull Request instance

  2. Do a self-review of your Pull Request

  1. Click the “Ready to review” button to take your Pull Request out of “draft”

  2. If necessary, add reviewers

  1. Tell your reviewers about the Pull Request

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

  2. Keep your branch up to date with main and re-run the “PR Deploy” Action

  1. Wait for approval (if needed) and merge your changes with the properly formatted commit message 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 either Lat/Lon or UTM coordinates.

  1. Monitor the Push Action

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

  1. Check Code Climate

  1. Move Jira task to DONE

  2. Celebrate