Contributing

Abstract

Kubernetes Operator Agent contribution guide.

Contributing#

Therefore we rely on you to test your changes sufficiently.

Pull Requests#

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests. See the above stated requirements for PR on this project.

Pull Request Title Linting#

We lint the title of your pull request to ensure it follows the Conventional Commits specification. This is done using GitHub actions and the action-semantic-pull-request workflow. We require the scope of the change to be included in the title. The scope should be the name of the chart you are changing. For example, if you are changing the argo-cd chart, the title of your pull request should be fix(argo-cd): Fix typo in values.yaml.

Documentation#

The documentation for each chart is generated with helm-docs. This way we can ensure that values are consistent with the chart documentation.

We have a script on the repository which will execute the helm-docs docker container, so that you don’t have to worry about downloading the binary etc. Simply execute the script (Bash compatible, might require sudo privileges):

./scripts/helm-docs.sh

Note

When creating your own README.md.gotmpl, don’t forget to add it to your .helmignore file.

Updating a chart README.md#

When updating the README.md.gotmpl inside a chart directory you must to run the helm-docs script to generate the updated README.md file. To reiterate, you should not edit the README.md file manually. It will be generated by the following command:

./scripts/helm-docs.sh

Note If you see changes to unrelated chart README.md files you may have accidentally updated a README.md.gotmpl file in another chart’s folder unintentionally or someone else failed to run this script. Please revert those changes if you do not intend them to be a part of your pull request.

Versioning#

Each chart’s version follows the semver standard.

New charts should start at version 1.0.0, if it’s considered stable. If it isn’t considered stable, it must be released as prerelease.

Any breaking changes to a chart (backwards incompatible) require:

  • Bump of the current Major version of the chart

  • State possible manual changes for this chart version in the Upgrading section of the chart’s README.md.gotmpl

New Application Versions#

Helm charts are intended to be created for all non-patched releases of Argo CD, Workflows, Rollouts, and Events. Associated dependencies, such as Redis, will use the version recommended by the associated release.

When selecting new application versions ensure you make the following changes:

  • values.yaml: Bump all instances of the container image version

  • Chart.yaml: Ensure appVersion matches the above container image and bump version

Please ensure chart version changes adhere to semantic versioning standards:

  • Major: Large chart rewrites, major non-backwards compatible or destructive changes

  • Minor: New chart functionality (sidecars), major application updates or minor non-backwards compatible changes

  • Patch: App version patch updates, backwards compatible optional chart features

Immutability#

Each release for each chart must be immutable. Any change to a chart (even just documentation) requires a version bump. Trying to release the same version twice will result in an error.

Chart Versioning#

Currently we require a chart version bump for every change to a chart, including updating information for older versions. This may change in the future.

Artifact Hub Annotations#

Since we release our charts on Artifact Hub we encourage making use of the provided chart annotations for Artifact Hub.

Changelog#

We want to deliver transparent chart releases for our chart consumers. Therefore we require a changelog per new chart release.

Changes on a chart must be documented in a chart specific changelog in the Chart.yaml Annotation Section.

A new artifacthub.io/changes needs to be written covering only the changes since the previous release.

Each change requires a new bullet point following the pattern. See more information Artifact Hub annotations in Helm Chart.yaml file.

- kind: {type}
  description: {description}

You can use the following template:

name: argo-cd
version: 5.19.12
...
annotations:
  artifacthub.io/changes: |
    - kind: added
      description: Something New was added
    - kind: changed
      description: Changed Something within this chart
    - kind: changed
      description: Changed Something else within this chart
    - kind: deprecated
      description: Something deprecated
    - kind: removed
      description: Something was removed
    - kind: fixed
      description: Something was fixed
    - kind: security
      description: Some Security Patch was included

Testing#

Testing Argo Workflows Changes#

Minimally:

helm install charts/argo-workflows -n argo
argo version

Follow these instructions for running a hello world workflow.

Testing Argo CD Changes#

Clean-up:

helm delete argo-cd --purge
kubectl delete crd -l app.kubernetes.io/part-of=argocd

Pre-requisites:

helm repo add redis-ha https://dandydeveloper.github.io/charts/
helm dependency update

Minimally:

helm install argocd  argo/argo-cd  -n argocd --create-namespace
kubectl port-forward service/argo-cd-argocd-server -n argocd 8080:443

In a new terminal:

argocd version --server localhost:8080 --insecure
# reset password to 'Password1!'
kubectl -n argocd patch secret argocd-secret \
  -p '{"stringData": {
      "admin.password": "$2a$10$hDj12Tw9xVmvybSahN1Y0.f9DZixxN8oybyA32Uy/eqWklFU4Mo8O",
      "admin.passwordMtime": "'$(date +%FT%T%Z)'"
  }}'
argocd login localhost:8080 --username admin --password 'Password1!'

# WARNING: server certificate had error: x509: certificate signed by
# unknown authority. Proceed insecurely (y/n)? y

Create and sync app:

argocd app create guestbook --dest-namespace default \
  --dest-server https://kubernetes.default.svc \
  --path guestbook --project default \
  --repo https://github.com/argoproj/argocd-example-apps.git
argocd app sync guestbook

Testing Charts#

As part of the Continuous Integration system we run Helm’s Chart Testing tool.

The checks for Chart Testing are stricter than the standard Helm requirements. For example, fields normally considered optional like maintainer are required in the standard spec and must be valid GitHub usernames.

Linting configuration can be found in ct-lint.yaml

The linting can be invoked manually with the following command:

./scripts/lint.sh

Publishing Changes#

Changes are automatically publish whenever a commit is merged to the main branch by the CI job (see ./.github/workflows/publish.yml).

Contents