Merge pull request #370 from oauth2-proxy/doc/update-contribution-guide

doc: update contribution guide

Author: pierluigilenoci

AGENTS.md

@@ -0,0 +1,35 @@
+# Agent Guidance for the oauth2-proxy Helm Chart
+
+This repository hosts the community Helm chart for deploying [oauth2-proxy](https://github.com/oauth2-proxy/oauth2-proxy). Automated or human agents working in this repo should prioritize clarity, reproducibility, and reviewer trust.
+
+## Mission and scope
+
+- Keep the chart aligned with upstream oauth2-proxy releases and Kubernetes best practices.
+- Ensure every functional change ships with updated values, docs, and tests where applicable.
+- Maintain a clear audit trail so reviewers can understand *why* a change exists and how it was validated.
+
+## Context to load first
+
+- `helm/oauth2-proxy/Chart.yaml` – chart metadata, versioning, Artifact Hub annotations.
+- `helm/oauth2-proxy/values.yaml` – defaults you must update when adding new flags/behavior.
+- `helm/oauth2-proxy/README.md` – source of truth for documented configuration knobs.
+- `ct.yaml` – configuration for `chart-testing`; run `ct lint --config ct.yaml` before requesting review.
+- `helm/oauth2-proxy/ci/*.yaml` – sample value files that double as regression cases.
+
+## Quality checklist before opening a PR
+
+- [ ] Chart version bumped when any template, values, or docs change.
+- [ ] `artifacthub.io/changes` updated when user-facing behavior changes.
+- [ ] New/changed values documented in both `values.yaml` (with clear comments) and `helm/oauth2-proxy/README.md` tables.
+- [ ] Tests/lint (`ct lint` and, if needed, `ct install`) executed and exits captured in the PR description.
+- [ ] Any required secrets or sample manifests documented so reviewers can reproduce.
+
+## AI attribution (keep it brief but visible)
+
+We encourage useful automation, but reviewers must know when AI meaningfully shaped a change. Mark substantial AI assistance by append a commit trailer such as `Assisted-by: <tool or service>`.
+
+Trivial autocomplete (variable names, single-line suggestions you fully rewrote) does **not** need disclosure. When in doubt, disclose.
+
+## Need updates?
+
+If the expectations in this file stop reflecting the team’s workflow, propose edits via an issue or PR referencing `agents.md`. Keeping these guidelines current helps both humans and agents land safe, reviewable changes.

CONTRIBUTING.md

@@ -1,10 +1,10 @@
 # Contributing
 
-This repository is the official **community maintained** helm chart for oauth2-proxy and is not to be confused with the helm chart published by bitnami. We rely on you to test your changes sufficiently.
+This repository is the official **community maintained** helm chart for OAuth2 Proxy and is not to be confused with the helm chart published by bitnami. 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.
+All submissions, including submissions by project members, require a review. We use GitHub pull requests for this purpose.
 
 ### Pull Request Title
 
@@ -16,7 +16,7 @@ The documentation in the chart [README.md](charts/oauth2-proxy) and the `values.
 
 ### Artifact Hub Annotation
 
-Since we release the chart on Artifact Hub we require you to update the `artifacthub.io/changes` annotation in the `Chart.yaml`.
+Since we have rolling release and publish the chart on Artifact Hub, we require you to update the `artifacthub.io/changes` annotation in the `Chart.yaml` for every PR.
 
 * [https://artifacthub.io/docs/topics/annotations/helm/](https://artifacthub.io/docs/topics/annotations/helm/)
 
@@ -25,11 +25,11 @@ Since we release the chart on Artifact Hub we require you to update the `artifac
 
 We follow the [semver standard](https://semver.org/) for the chart version and application version.
 
-Always consider your changes and try to avoid breaking changes where possible.
+Always consider your changes and try to avoid breaking changes whenever possible.
 
 ### New Application Versions
 
-The application version is only to be updated if a new release of the oauth2-proxy application repo was published.
+The application version is only to be updated if a new release of the OAuth2 Proxy application repo was published.
 
 ### Immutability
 
@@ -38,27 +38,27 @@ Each release must be immutable. Any change to a chart (even just documentation)
 
 ## Testing
 
-When making changes to the logic or resources of the chart please make sure you tested those changes in two ways:
+When making changes to the logic or resources of the chart, please make sure you tested those changes in two ways:
 
 * Existing helm release with the chart version before your changes: `helm upgrade`
-* Fresh helm release with you changes: `helm install`
+* Fresh helm release with your changes: `helm install`
 
 
 ### Testing Charts
 
-As part of the Continuous Integration system we run Helm's [Chart Testing](https://github.com/helm/chart-testing) tool.
+As part of the Continuous Integration, we run Helm's [Chart Testing](https://github.com/helm/chart-testing) tool.
 
 The checks for Chart Testing are stricter than the standard Helm requirements.
 
 The configuration can be found in [ct.yaml](ct.yaml)
 
-If you have `ct` installed you can manually invoke the linting with the following command:
+If you have `ct` installed, you can manually invoke the linting with the following command:
 
 ```shell
 ct lint --config ct.yaml
 ```
 
-If you want to run the tests locally we recommend to use [kind](https://kind.sigs.k8s.io).
+If you want to run the tests locally, we recommend to use [kind](https://kind.sigs.k8s.io) to setup a local cluster.
 
 Prerequisites:
 
@@ -67,12 +67,12 @@ Prerequisites:
 kubectl apply --server-side -f https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/release-0.78/example/prometheus-operator-crd/monitoring.coreos.com_servicemonitors.yaml
 ```
 
-Run the tests:
+Run the tests (takes up to 10 minutes):
 
 ```shell
 ct --config ct.yaml install
 ```
 
 ## Publishing Changes
 
-Changes are automatically publish whenever a commit is merged to the `main` branch by the CI job (see `./.github/workflows/release.yml`).
+Changes are automatically publish, whenever a commit is merged to the `main` branch by the CI job (see `./.github/workflows/release.yml`).

README.md

@@ -1,6 +1,6 @@
 # manifests
 
-For hosting manifests to allow for the deployment of OAuth2-Proxy/OAuth2-Proxy
+For hosting manifests to allow for the deployment of [OAuth2 Proxy](https://github.com/oauth2-proxy/oauth2-proxy)
 
 ## Helm Chart
 
@@ -20,6 +20,11 @@ ct lint --all --config ct.yaml
 ct install --all --config ct.yaml
 ```
 
+## Contributing
+
+If you want to contribute to this project, please make yourself familiar with the [CONTRIBUTING.md](https://github.com/oauth2-proxy/manifests/tree/main/CONTRIBUTING.md) guide before opening a PR or issue.
+Be aware this is just the Helm chart / manifest repository. Actual problems with the application OAuth2 Proxy itself should be reported in the main project repository.
+
 ## Verify Signed Helm Charts
 
 With the introduction of cosign for signing artifacts you can verify the
@@ -43,19 +48,19 @@ more about how keyless signing is done, visit the official documentation about
 
 
 ## Code of Conduct
-Participation in the OAuth2-Proxy project is governed by the [CNCF Code of Conduct](https://github.com/oauth2-proxy/oauth2-proxy/tree/master/CODE_OF_CONDUCT.md).
+Participation in the OAuth2 Proxy project is governed by the [CNCF Code of Conduct](https://github.com/oauth2-proxy/oauth2-proxy/tree/master/CODE_OF_CONDUCT.md).
 
 ## License
 
-OAuth2-Proxy is distributed under [The MIT License](https://github.com/oauth2-proxy/oauth2-proxy/tree/master/LICENSE).
+OAuth2 Proxy is distributed under [The MIT License](https://github.com/oauth2-proxy/oauth2-proxy/tree/master/LICENSE).
 
 [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Foauth2-proxy%2Fmanifests.svg?type=large&issueType=license)](https://app.fossa.com/projects/git%2Bgithub.com%2Foauth2-proxy%2Fmanifests?ref=badge_large&issueType=license)
 
-The OAuth2-Proxy helm chart is distributed under [Apache License 2.0](https://github.com/oauth2-proxy/manifests/tree/main/LICENSE).
+The OAuth2 Proxy helm chart is distributed under [Apache License 2.0](https://github.com/oauth2-proxy/manifests/tree/main/LICENSE).
 
 ## Trademarks
 
-OAuth2-Proxy is a [Cloud Native Computing Foundation](https://cncf.io) Sandbox project.
+OAuth2 Proxy is a [Cloud Native Computing Foundation](https://cncf.io) Sandbox project.
 
 ![CNCF](https://www.cncf.io/wp-content/uploads/2023/04/cncf-main-site-logo.svg)