Skip to main content

Contributor Guide

Contributing to Zarf

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

The following is a set of guidelines for contributing to Zarf. These are mostly guidelines, not rules. Use your best judgement, and feel free to propose changes to this document in a pull request.

Developer Experience​

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


  • We do trunk-based development 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 the trunk that isn't releasable
  • We perform automated testing on all changes before they get merged to the trunk
  • We create immutable release artifacts

Developer Workflow​

Here's what a typical "day in the life" of a Zarf developer might look like. Keep in mind that other than things that are required through automation these aren't hard-and-fast rules. When in doubt, the process outlined here works for us.

🔑 == Required by automation

  1. Pick an outstanding issue to work on, set yourself as the assignee, and move it to "Doing Now" in the Kanban Board. The "Ready to Start" and "Planned" columns are mostly prioritized (rank order) according to feedback from our users and other inputs, but don't feel like you have to pick from the top of the pile if something else is jumping out at you.

  2. Write up a rough outline of what you plan to do in the issue so you can get early feedback. Clearly announce any breaking changes you think need to be made.

  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.

    ⚠ī¸ NOTE: If you are an external third-party contributor you will need a core-member of the zarf project to re-sign your commits; you will still receive authorship for the work you have contributed however.

  4. 🔑 Create a branch off the trunk, or a fork if you are an external contributor.

  5. 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. Around here we aren't afraid to show unfinished work. It helps us get feedback more quickly.

  6. 🔑 Create a Pull Request (or mark it Ready for Review if you've been working in a Draft PR).

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

  8. Clearly announce any breaking changes that have been made.

  9. 🔑 Get at least 1 peer-review approval.

  10. 🔑 Merge the PR into the trunk. We tend to prefer "Squash and Merge" but if your commits are on-point and you want to preserve them in the Git history of the trunk that's fine too.

  11. Delete the branch

  12. Close the issue if it got 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.


This section dives deeper into how we test Zarf

Pre-Commit Hooks and Linting​

In this repo we use pre-commit hooks for automated validation and linting. The CI pipeline will (eventually) validate that all of the hooks pass so we strongly recommend that you install the hooks locally or you'll be spending a lot of time manually fixing issues that could be fixed automatically very quickly.

Pre-Commit Prerequisites​

  1. Install pre-commit
  2. Install go
  3. Install golangci-lint
  4. Run pre-commit install in the repo to install the pre-commit hooks. This will make the hooks run automatically each time you git commit. If you want to skip the hooks for any reason you can run git commit --no-verify to skip them.

ℹī¸ HINT: Consider automatically enabling the hooks in every Git repository

End2End 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. You can learn more about testing of Zarf here.

⚠ī¸ NOTE: If you are an external third-party contributor you will need a core-member of the zarf project to run the CI tests/checks for you. It is strongly recommended to run the tests locally first as documented in the link above.


In this section you'll find documentation on documentation! Pun absolutely intended 😄

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