Skip to content

Latest commit

 

History

History
79 lines (46 loc) · 4.91 KB

CONTRIBUTING.md

File metadata and controls

79 lines (46 loc) · 4.91 KB
Raw

Contributing to Zarf

First off, thanks so much for wanting to help out! 🎉

Developer Experience

Continuous Delivery is core to our development philosophy. Check out https://minimumcd.org for a good baseline agreement on what that means.

Specifically:

  • We do trunk-based development (main) with short-lived feature branches that originate from the trunk, get merged to the trunk, and are deleted after the merge
  • We don't merge code into main that isn't releasable
  • We perform automated testing on all changes before they get merged to main
  • We create immutable release artifacts

Developer Workflow

🔑 == Required by automation

  1. Look at the next due release milestone and pick an issue that you want to work on. If you don't see anything that interests you, create an issue and assign it to yourself.

  2. Assign yourself to the issue and drop a comment in the issue to let everyone know you're working on it.

  3. 🔑 Set up your Git config to GPG sign all commits. Here's some documentation on how to set it up. You won't be able to merge your PR if you have any unverified commits.

  4. Create a Draft Pull Request as soon as you are able to, even if it is just 5 minutes after you started working on it. We lean towards working in the open as much as we can. If you're not sure what to put in the PR description, just put a link to the issue you're working on. If you're not sure what to put in the PR title, just put "WIP" (Work In Progress) and we'll help you out with the rest.

  5. 🔑 Automated tests will begin based on the paths you have edited in your Pull Request. More information on these tests can be found here.

    ⚠️ NOTE: If you are an external third-party contributor, the pipelines won't run until a CODEOWNER approves the pipeline run.

  6. 🔑 Be sure to use the needs-adr,needs-docs,needs-tests labels as appropriate for the PR. Once you have addressed all of the needs, remove the label.

  7. Once review is complete and approved, a core-member of the zarf project will merge your PR. If you are an external third-party contributor, two core-members of the zarf project will be required to approve the PR.

  8. Close the issue if it is fully resolved by your PR. Hint: You can add "Fixes #XX" to the PR description to automatically close an issue when the PR is merged.

Testing

This section dives deeper into how we test Zarf

(Optional) Pre-Commit Hooks and Linting

In this repo you can optinally use pre-commit hooks for automated validation and linting, but if not CI will run these checks for you.

Code Testing

Our E2E tests can be found in the /test folder and follow the journey of someone as they would use the Zarf CLI. In CI these tests run against our currently supported cluster distros, and are the primary way that Zarf code is tested.

Our Unit tests can be found as *_test.go files inside the package that they are designed to test. These are also run in CI and are designed to test small functions with clear interfaces that would be difficult to test otherwise. As a general rule, we are limiting unit tests to the src/pkg/* folder.

All of our tests should be able to be run locally or in CI. You can learn more about testing of Zarf here.

Documentation

Architecture Decision Records (ADR)

We've chosen to use ADRs to document architecturally significant decisions. We primarily use the guidance found in this article by Michael Nygard with a couple of tweaks:

  • The criteria for when an ADR is needed is undefined. The team will decide when the team needs an ADR.
  • We will use the tool adr-tools to make it easier on ourselves to create and maintain ADRs.
  • We will keep ADRs in the repository under docs/adr/NNNN-name-of-adr.md. adr-tools is configured with a dotfile to automatically use this directory and format.

How to use adr-tools

# Create a new ADR titled "Use Bisquick for all waffle making"
adr new Use Bisquick for all waffle making

# Create a new ADR that supersedes a previous one. Let's say for example that the previous ADR about Bisquick was ADR number 9.
adr new -s 9 Use scratch ingredients for all waffle making

# Create a new ADR that amends a previous one. Let's say the previous one was ADR number 15
adr new -l "15:Amends:Amended by" Use store-bought butter for all waffle making

# Get full help docs. There are all sorts of other helpful commands that help manage the decision log.
adr help