Skip to content

Latest commit

 

History

History
196 lines (119 loc) · 7.37 KB

CONTRIBUTING.md

File metadata and controls

196 lines (119 loc) · 7.37 KB
Raw

Contributing

Prerequisites

  • Homebrew
  • Helm >3.8.0
  • Access to a K8s environment
  • Prettier
  1. Install make, pre-commit with brew bundle
  2. Install the helm-unittest Helm plugin: 
    helm plugin install https://github.com/helm-unittest/helm-unittest --version=>0.6.0

Set Up

Clone this repository with git.

The default branch is rc, which contains the latest release candidate of the Universal Broker Helm Chart. The main branch is used to create releases of the Universal Broker Helm Chart only, and should not be committed to directly.

Building

From within the cloned repository, fetch dependencies for the Universal Broker Helm Chart:

cd snyk-universal-broker
helm dep up

Writing Tests

Unit Tests

All unit tests end in _test.yaml, and are contained within snyk-universal-broker/tests.

Identify if the test relates to an already existing test suite - if not, create a new file within this directory.

Each test must include the default values file. Any other values may either be set in each test suite, or (if re-used across many suites) defined in the fixtures directory.

Snapshot testing is not permitted.

Integration Tests

An integration exists that leverages the Snyk API to perform an import. This test is executed on each PR, written in TypeScript and is contained within .circleci/scripts/testImport/. This test requires a Snyk Org to be configured with the Universal Broker ahead of time.

Running Tests

From within the cloned repository, execute the helm-unittest plugin:

helm unittest snyk-universal-broker

Any test failures may be interrogated with the debug (-d), quick (-q) flags, and by targeting a specific test file (-f):

helm unittest -d -q -f tests/name_of_test.yaml snyk-universal-broker

Any rendered templates will be stored within a .debug directory.

Code Style

General

An .editorconfig is included with this repository.

Helm

Consider the use of Helm Templates to reduce duplication. Deeply nested Helm values are discouraged.

TypeScript

Prettier is used to format .ts files, with configuration in prettier.config.mjs.

Markdown

Prettier will also format .md files.

Updating Documentation

Any changes to Helm values must be reference in both the values.yaml and values.schema.json files.

Within the values.yaml file, ensure the value exists within an appropriately named section (denoted by ## @section). If one does not exist that is relevant, add one.

Each value must be accompanied with a description:

# @@param myNewValue [modifier?] Description

See the Bitnami Readme Generator for options.

If a value is added without a description, the pre-commit hook will fail.

Creating Branches

Branches must be created with the following format:

type/description-of-change

Where type must be one of the recognised conventional commit types (feat, fix, docs, etc.)

When creating a new branch, use rc as the base.

Creating Commits

Commits must follow the conventional commit standard.

Type Description
feat A new feature
fix A fix for an existing feature
chore Changes to build, workflow or pipelines
test Changes to tests for existing features
refactor Changes which do not affect existing features
docs Changes to documentation for existing features
revert Reverting a previous commit

Commits are consumed when creating a release to populate release notes. A commit message that focuses on why something changes instead of what changes can be more meaningful.

Breaking changes are not permitted. Any changes must be backwards compatible.

All commits must be signed.

Pre Commit Hooks

pre-commit will run before each commit, validating:

  • No secrets are part of this commit
  • Commits are well formed
  • The README.md document is up-to-date with content from the values.yaml file
  • Any TypeScript is appropriately formatted
  • helm-unittest passes

All hooks must pass before creating a successful commit.

Creating Pull Requests

All pull requests should initially be created as Drafts; this ensures tests pass before a review is requested. Pull Requests should target the rc branch.

Pull Request Checks

When raising a pull request (and on each subsequent commit to the branch associated with a pull request) CircleCI will execute a Pull Request pipeline. The following steps are carried out:

  • Secret and security scanning
  • Chart Validation (helm-unittest, kubeconform)
  • Documentation Validation (content in README.md matches values.yaml)
  • Deploy and Test (helm install and execute the Snyk Import integration test)

These stages must pass before a PR may be merged. Once ready, mark the PR as ready for review.

Merging Pull Requests

The "squash and merge" method should not be used, as this masks the commit history of rc when merging to main.

Creating Releases

The release process is orchestrated by CircleCI, and controlled by semantic-release, with configuration located in release.config.mjs. This process occurs on the rc and main branches.

Release Process

  1. Commits are analyzed by semantic-release to generate Release Notes and a CHANGELOG entry.
  2. The Universal Broker Helm Chart is packaged with the version as determined by semantic-release
  3. A GitHub Release (or Pre-Release) is created with the packaged Helm Chart
  4. The packaged Helm Chart is pushed to Dockerhub under snyk/snyk-universal-broker
  5. The Helm Chart is signed with cosign

Pre-Release

Every merge to the rc branch creates a pre-release candidate, with version x.y.z-rc.N, where x.y.z is the next version determined by semantic-release, and N is incremented by one from the previous pre-release candidate. Versions may be pulled by Helm with:

helm pull oci://registry-1.docker.io/snyk/snyk-universal-broker --version x.y.z-rc.N

Release

When ready to create a public release, a PR is created from rc to main. The chore: prefix should be used to avoid mutating the version.

When merged, a release is created with version x.y.z. This version will drop the -rc.N suffix, and will become the default version when the Universal Broker Helm Chart is pulled.

Chart Signing

The GitHub Actions certificate is used to perform keyless signing with cosign upon each pre-release and public release. See the GitHub Actions Workflow for steps.

Removing a Release

If a release must be removed:

  • Delete the associated GitHub Release. Do not delete the tag to avoid version collision
  • Delete the Helm Chart and corresponding signature artefact from DockerHub