Contributing to Flux

Contributing

Note: In this document we define the contribution process for the Flux project and community. These guidelines apply to all git repositories in the fluxcd GitHub org.

For more detailed docs, please refer to the following docs for

Flux is Apache 2.0 licensed and accepts contributions via GitHub pull requests. This document outlines some of the conventions on to make it easier to get your contribution accepted.

We gratefully welcome improvements to issues and documentation as well as to code.

Welcome

We gratefully welcome all kinds of contributions, including code, issues, documentation, external tools, advocacy and community work. All members of the Flux community, including contributors, are expected to uphold the Flux community Values and Code of Conduct.

Communications

For realtime communications we use Slack: To join the conversation, simply join the CNCF Slack workspace and use the #flux-contributors channel.

To discuss ideas and specifications we use Github Discussions.

For announcements we use a mailing list as well. Simply subscribe to flux-dev on cncf.io to join the conversation (there you can also add calendar invites to your Google calendar for our Flux meeting).

Semantic Versioning

The Flux project and community git repositories maintain a strong commitment to clear communication about backwards compatibility. For this reason, all code contributions must follow the Semantic Versioning 2.0.0 Specification (SemVer) per https://semver.org/, so that users can trust compatibility based on version scheme.

Acceptance policy

These things will make a PR more likely to be accepted:

  • a well-described requirement
  • new code follows the conventions in old code
  • a good commit message (see below)
  • all code must abide Go Code Review Comments
  • names should abide What’s in a name
  • code must build on both Linux and Darwin, via plain go build

In general, we will merge a PR once one maintainer has endorsed it. For substantial changes, more people may become involved, and you might get asked to resubmit the PR or divide the changes into more than one PR.

Testing Requirements

We require the following:

  • code should have appropriate test coverage and tests should be written to work with go test
  • new tests follow the conventions of existing tests
  • regression tests

Regression tests are important because they ensure that the code change did not break any existing features. Here is a commit with regression tests for you to refer.

Certificate of Origin

By contributing to this project you agree to the Developer Certificate of Origin (DCO). This document was created by the Linux Kernel community and is a simple statement that you, as a contributor, have the legal right to make the contribution.

We require all commits to be signed. By signing off with your signature, you certify that you wrote the patch or otherwise have the right to contribute the material by the rules of the DCO:

Signed-off-by: Jane Doe <jane.doe@example.com>

The signature must contain your real name (sorry, no pseudonyms or anonymous contributions) If your user.name and user.email are configured in your Git config, you can sign your commit automatically with git commit -s.

This is automatically checked by the Probot: DCO integration across all fluxcd GitHub org repositories.

Commit signoff is a simple statement that you, as a contributor, have the legal right to make the contribution. See git help commit:

The meaning of a signoff depends on the project, but it typically certifies that committer has the rights to submit this work under the same license and agrees to a Developer Certificate of Origin (see http://developercertificate.org/ for more information).

CLI

When signing commits with git commit -s, signoff is drawn automatically from your user.name and user.email git configs. If you choose to manually add a signoff line to your commit message, it must be properly formatted and match your commit information. For example, when using the GitHub private email option you must set your git config email accordingly. For those who wish to ensure this is always done in your CLI, consider implementing something like this gist.

Format of the Commit Message

For the GitOps Toolkit controllers we prefer the following rules for good commit messages:

  • Limit the subject to 50 characters and write as the continuation of the sentence “If applied, this commit will …”
  • Explain what and why in the body, if more than a trivial change; wrap it at 72 characters.

The following article has some more helpful advice on documenting your work.

Thank You

Contributors are crucial to ensuring the Flux project continues to fairly represent community interests. Thank you for all that you do.