Skip to content

CONTRIBUTING.adoc

Latest commit

 

History

History
123 lines (80 loc) · 4.47 KB

CONTRIBUTING.adoc

File metadata and controls

123 lines (80 loc) · 4.47 KB

CONTRIBUTING

Thank you for your interest in contributing to this project. Here is a none exclusive list of contribution you can do.

Documentation

This project would benefit from clearer policy README files. Please improve each policy’s README to explain how to use and configure the policy.

To inspect a policy bundle locally (manifest and default values):

# Show the generated manifest (uses files in the policy bundle directory)

updatecli manifest show --config updatecli.d --values values.yaml

# Show the manifest and render a graph (Mermaid)

updatecli manifest show --config updatecli.d --values values.yaml --graph --graph-flavor mermaid

Notes:

  • --config updatecli.d reads policy manifests shipped inside the policy bundle.

  • --values values.yaml overrides default policy values for local inspection.

When running policies, prefer pinning by version or digest to ensure reproducible runs:

  • By tag: ghcr.io/updatecli/policies/autodiscovery/golang:1.0.0

  • By digest: ghcr.io/updatecli/policies/autodiscovery/golang@sha256:<digest>

Authentication:

  • Public pulls usually work, but authenticating with GHCR reduces rate limits:

docker login ghcr.io

  • For private bundles, provide registry credentials to your runtime or via Updatecli’s registry auth options.

Publishing:

  • Policies in this repository are published automatically by CI when Policy.yaml version is bumped.

  • See the Policy.yaml template below and ensure you update the version field for releases.

Policy inspection and usage summary:

  • Inspect: updatecli manifest show --config updatecli.d --values values.yaml

  • Dry-run: updatecli diff ghcr.io/updatecli/policies/<path>:<version>

  • Apply: updatecli apply --config ghcr.io/updatecli/policies/<path>:<version>

Tip: add a short example values.yaml in each policy README to help users test quickly.

Updating Policy

Before changing an existing policy, open a GitHub issue to discuss the proposed change. Use the issue to explain:

  • Motivation and user impact

  • Backwards compatibility implications

  • Required changes to Policy.yaml, values.yaml, or updatecli.d

  • Testing plan (how the change will be validated)

When preparing a PR:

  • Bump Policy.yaml version for behavioural changes (semantic versioning).

  • Update CHANGELOG.md and the policy README.md with usage and configuration changes.

  • Add or update values.yaml examples if defaults change.

  • Ensure policy validation CI (lint/manifest tests) passes.

PR checklist:

  • ❏ Issue opened describing the change (link in PR)

  • ❏ Policy.yaml version updated when needed

  • ❏ CHANGELOG.md updated

  • ❏ README and example values.yaml updated

  • ❏ All CI checks pass (policy validation workflow)

Notes:

  • Policies are published automatically by CI when Policy.yaml.version is updated.

  • For large or breaking changes, discuss a migration plan in the issue and notify maintainers.

  • For security-related changes, include an explanation and coordinate disclosure with maintainers.

New Policy

A new policy can be added by creating a new folder under the updatecli/policies directory. The subfolder path will be used as the policy name.

For example if we want to create a policy named autodiscovery/golang, we need to create a folder named updatecli/policies/autodiscovery/golang. This policy will be named ghcr.io/updatecli/policies/autodiscovery/golang and will be published on ghcr.io docker registry.

The policy folder must contain:

  • Policy.yaml file which contains the policy metadata.

  • updatecli.d directory which contains the policy configuration files.

  • README.md file which contains the policy documentation.

  • CHANGELOG.md file which contains the policy changelog.

  • values.yaml file which contains the default values for the policy.

Policy.yaml

The Policy.yaml file must contain at least the following fields:

url: <link to this git repository>
documentation: <link to the policy documentation>
source: <link to this policy code>
version: <policy version>
changelog: <link to this policy changelog>
description: <policy description with maximum 512 characters>

Version

The version must be a valid semantic version. For example 1.0.0 or 1.0.0-beta.1 The version will be used as the "tag" for the policy such as ghcr.io/updatecli/policies/autodiscovery/golang:1.0.0

Any change to the policy code must be reflected by a new version. Policies are automatically published on ghcr.io if the version is updated.