Skip to content

Latest commit

 

History

History
76 lines (59 loc) · 5.53 KB

CONTRIBUTING.md

File metadata and controls

76 lines (59 loc) · 5.53 KB
Raw

Contributing to Cerbos

Thank you for your interest in Cerbos. We welcome contributions from the community. Please note that we have a code of conduct that must be followed when interacting with this project. In addition, please read the guidelines below to ensure that your contributions have a better chance of being accepted.

Submitting pull requests

  • Before submitting a pull request, please raise an issue in the GitHub repository and provide information about the problem you are trying to fix and how you plan to address it. Include as much detail as possible to make it easier for others to understand your thought process.
  • Wait for the project maintainers and other community members to respond to your proposal and clearly agree on a course of action.
  • Create your patch, constraining yourself to what was agreed on the issue. If previously unforeseen problems arise and you have to make significant changes to an area that wasn’t discussed in the issue, make sure to go back to the issue to discuss the new circumstances and get buy-in from the people who are involved.
  • Run the pre-commit checks that are appropriate for the kind of change. (See below for details.)
  • Submit your pull request.
    • We require all pull requests to follow the conventional commit format.
    • Use closing keywords to link the PR to the original issue.
    • At least one approval from a maintainer is required to merge the pull request.

Submitting pull requests for code changes

  • Write idiomatic Go. Effective Go is the canonical source while the Uber style guide contains a lot of good advice as well.
  • Make sure each source file contains the appropriate licence header: 
    Copyright 2021-2024 Zenauth Ltd.
SPDX-License-Identifier: Apache-2.0
  • Add tests to cover the functionality you are adding or modifying.
  • Add new documentation or update existing content to ensure that the documentation stays consistent with the change you are introducing. See below for tips on writing documentation.
  • Avoid introducing new dependencies if possible. All dependencies must have an appropriate open source licence (Apache-2.0, BSD, MIT).
  • Make sure your code is gofmted. Run make lint and fix any warnings produced by the linter.
  • Sign-off your commits to provide a DCO. You can do this by adding the -s flag to your git commit command. 
    git commit -s -m 'bug: Fix for bug X'

Submitting pull requests for documentation changes

  • We use Asciidoctor to write documentation. Please note that some AsciiDoctor features might not be available in Antora, the static site generation software we use.
  • Use simple, inclusive language. Also refer to the Microsoft Style Guide for general advice on writing good documentation.
  • Do not add third-party content in-line without attribution. Use links where possible.
  • Ensure that any binary assets (images, videos, etc.) are added to Git LFS.
  • Sign-off your commits to provide a DCO. You can do this by adding the -s flag to your git commit command. 
    git commit -s -m 'bug: Fix for bug X'

Developing Cerbos

Cerbos is developed using the Go programming language. Check the go directive in the go.mod file to find out the minimum version of Go required.

Just (a better alternative to make) is used as the build scripting system and needs to be installed on the system. Other required build tools are automatically downloaded on demand using the versions defined in tools/go.mod.

Run just to list all available build targets. Some of the frequently used targets are:

  • just tests: Run all tests.
  • just build: Compile, test and build the Cerbos binaries and container. Binaries will be output to the dist directory. The container name would be ghcr.io/cerbos/cerbos:<VERSION>-prerelease.
  • just pre-commit: Run tests, lint, and generate code and documentation. Run this before submitting a PR to make sure your code is ready to submit.
  • just dev-server: Start a Cerbos server. Alternatively, use just cerbos [ARGS] or just cerbosctl [ARGS] to launch Cerbos or Cerbosctl from source.
  • just docs: Generate docs and preview in browser.

Getting Help