Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
113 lines (75 loc) · 6.21 KB

CONTRIBUTING.md

File metadata and controls

113 lines (75 loc) · 6.21 KB

Regarding contributions

Welcome! We're happy to have you here. All types of contributions are encouraged and valued.

See the Table of Contents for different ways to help and details about how this project handles them. Please make sure to read the relevant section before making your contribution. It will make it a lot easier for us maintainers and smooth out the experience for all involved. We look forward to your contributions!

The project has defined a code of conduct to ensure a welcoming and friendly environment. Please adhere to it in all interactions.

Table of Contents

I want to contribute

There are many ways to contribute. Improving the documentation is no less important than improving the code of the library itself. If you find a typo in the documentation or have made improvements, do not hesitate to create a GitHub issue or preferably submit a GitHub pull request.

There are many other ways to help. In particular, improving, triaging, and investigating issues or reviewing other developers' pull requests are valuable contributions that decrease the burden on the project maintainers.

Another way to contribute is to report issues you're facing, and give a "thumbs up" on issues that others reported and that are relevant to you. It also helps us if you spread the word: reference the project from your blog and articles, link to it from your website, or simply star it in GitHub to say "I use it".

Suggesting enhancements

This section guides you through submitting an enhancement suggestion, including completely new features and minor improvements to existing functionality. Following these guidelines will help maintainers and the community understand your suggestion and find related suggestions.

Before Submitting an Enhancement

  • Make sure that you are using the latest version.
  • Read the documentation carefully and find out if the functionality is already covered, maybe by an individual configuration.
  • Find out whether your idea fits with the scope and aims of the project.

How do I submit a good enhancement suggestion?

  • Use a clear and descriptive title for the issue to identify the suggestion.
  • Provide a step-by-step description of the suggested enhancement in as many details as possible.
  • Describe the current behavior and explain which behavior you expected to see instead and why. At this point you can also tell which alternatives do not work for you.
  • You may want to include screenshots and animated GIFs which help you demonstrate the steps or point out the part which the suggestion is related to.
  • Explain why this enhancement would be useful to most users. You may also want to point out other projects that solved it better and could serve as inspiration.

Your first code contribution

Before opening a Pull Request (PR), please consider the following guidelines:

  • Please make sure that the code builds perfectly fine on your local system.
  • The PR must meet the code standards and conventions of the project.
  • Explanatory comments related to code functions are strongly recommended.

And finally, when you are satisfied with your changes, open a new PR.

Contribution workflow

Here’s how we suggest you go about proposing a change to this project:

  1. Fork this project to your account.
  2. Create a branch for the change you intend to make.
  3. Make your changes to your fork.
  4. Send a pull request from your fork’s branch to our main branch.

Using the web-based interface to make changes is fine too, and will help you by automatically forking the project and prompting to send a pull request too.

Creating a release

Default flow (automated):

  1. Run Release PR workflow (.github/workflows/release-pr.yml) with version (X.Y.Z or vX.Y.Z).
  2. Review and merge the generated PR (chore(release): prepare vX.Y.Z).
  3. Tag and push the release from main:
    • git switch main && git pull
    • git tag -a vX.Y.Z -m vX.Y.Z -s
    • git push origin vX.Y.Z
  4. Release Publish workflow (.github/workflows/release-publish.yml) runs automatically on tag push and uploads signed artifacts to the GitHub release.

Manual fallback:

  1. If needed, run Release Publish via workflow_dispatch with an existing tag.

Signing model:

  • Sigstore keyless signatures are generated in CI for every release artifact.
  • GPG detached signatures are also generated for compatibility.
  • Required repository secrets for GPG signing in CI:
    • RELEASE_GPG_PRIVATE_KEY (ASCII-armored private key)
    • RELEASE_GPG_PASSPHRASE (passphrase for the private key)

Verification examples:

# Sigstore
cosign verify-blob --signature artifact.sig --certificate artifact.pem --certificate-oidc-issuer https://token.actions.githubusercontent.com --certificate-identity-regexp 'https://github.com/.+' artifact

# GPG
gpg --verify artifact.asc artifact

Recommended VSCode extensions

We recommend installing the following VSCode extensions to encourage consistent code style and formatting: