Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
126 lines (77 loc) · 8.13 KB

CONTRIBUTING.md

File metadata and controls

126 lines (77 loc) · 8.13 KB

Contributing to Zarf

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

This document describes the steps and requirements for contributing a bug fix or feature in a Pull Request to Zarf! If you have any questions about the process or the pull request you are working on feel free to reach out in the Zarf Kubernetes Slack Channel. The doc also details a bit about the governance structure of the project.

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

Pre-Commit Hooks and Linting

We use pre-commit to manage our pre-commit hooks, which lint and format code before it's committed.

Prerequisites

  • Go matching the version in the project go.mod, available on your PATH. Our pre-commit hooks invoke golangci-lint directly from your PATH rather than managing a Go environment (see Supply-chain notes below).
  • Python 3, required by pre-commit itself and by several of our hooks.
  • pre-commit, installed per the pre-commit installation guide.

Setup

# install hooks into .git/hooks
pre-commit install

# install golangci-lint (used by the goimports and lint hooks)
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

Every commit now runs the hooks; linting can also be invoked directly via make lint-go.

Supply-chain notes

.pre-commit-config.yaml is deliberately configured to reduce the attack surface of the contributor loop:

  • External hook repos are pinned by commit SHA, with the original tag in a trailing comment. Git tags are mutable on the server side; pinning by SHA ensures a fresh pre-commit install or pre-commit autoupdate cannot silently pull a retargeted tag. This matches the SHA-pinning convention we already use for GitHub Actions.
  • Go-based hooks use language: system so pre-commit invokes the golangci-lint already on your PATH rather than managing its own Go environment or fetching a toolchain from go.dev. This keeps lint/format behavior aligned with CI and avoids introducing a second trust root.

When upgrading a pinned hook, run pre-commit autoupdate --freeze — the --freeze flag writes the resolved commit SHA (rather than the tag) back into rev:. Update the trailing tag comment to match, so the config stays auditable.

Contributing Guidelines

Zarf is a tool used within the United States Government and as such security is our highest priority. Contributors external to Defense Unicorns or non-Zarf maintainers will require two (2) reviewers.

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. Drop a comment in the issue to let everyone know you're working on it and submit a Draft PR (step 4) as soon as you are able. If you have any questions as you work through the code, reach out in the Zarf Kubernetes Slack Channel.

  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. In addition to signing your commits, you will also need to sign-off on commits stating you agree to the contribution terms.

    • This can be done by using -s with your git commit - adding "Signed-off-by" line automatically.
    • Example: git commit -s -m "fix: add missing newline"

  5. Create a Draft Pull Request as soon as you can, 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.

  6. 🔑 Automated tests will begin based on the paths you have edited in your Pull Request.

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

  7. 🔑 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.

  8. Once the 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.

  9. 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

A more comprehensive guide to testing can be found here.

Our E2E tests can be found in the src/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.

Documentation

The CLI docs (located at site/src/content/docs/commands), and zarf.schema.json are autogenerated from make docs-and-schema. Run this make target locally to regenerate the schema and documentation each time you make a change to the CLI commands or the schema, otherwise CI will fail.

We do this so that there is a git commit signature from a person on the commit for better traceability, rather than a non-person entity (e.g. GitHub CI token).

Examples

Zarf maintains a gallery of different examples to give users living documentation on real-life Zarf use cases. Contributions are highly welcome. When adding an example, be sure to also add it to the make target build-examples.

Zarf Enhancement Proposals (ZEP)

Zarf Enhancement Proposals (ZEP) provides a process to propose and document important decision points. Proposal topics includes large features, significant changes to the UX, and architecture re-designs requiring considerable effort. Anyone can create a ZEP by visiting the zarf-dev/proposals repository.

ZEPs replace Architecture Decision Records (ADRs) which are kept at the base of the Zarf repository for historical purposes.

Governance

Technical Steering Committee

The Technical Steering Committee (the "TSC") will be responsible for all technical oversight of the project. The TSC may elect a TSC Chair, who will preside over meetings of the TSC and will serve until their resignation or replacement by the TSC. Current members of the TSC include:

Austin Abro

Affiliation: Defense Unicorns GitHub: @AustinAbro321

Brandt Keller

Affiliation: Defense Unicorns GitHub: @brandtkeller

Danny Gershman

Affiliation: Radius Method GitHub: @dgershman

Jeff McCoy (TSC Chair)

Affiliation: Defense Unicorns GitHub: @jeff-mccoy

Wayne Starr

Affiliation: Defense Unicorns GitHub: @Racer159