diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3b7764d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,20 @@ +# AGENTS + +This document describes how AI agents should work with this repository. The goal is to keep changes safe, consistent, and aligned with our GitOps usage of this repo. + +**Non-negotiables** + +- This repository is a **component catalog** (reusable building blocks for OpenStack on Kubernetes), not a full cluster or environment layout. +- **CI workflows** in [`.github/workflows/`](.github/workflows/) are the source of truth for validation commands. Do not invent new checks; mirror what those workflows run. +- **Do not** open pull requests or push to the remote without an explicit human request. A human must review before any push or PR. See [CONTRIBUTING.md#ai-assistants-and-agent-tooling](CONTRIBUTING.md#ai-assistants-and-agent-tooling). +- **Conventional Commits**; add `AI-Tool` / `AI-Model` footers when an AI assistant contributed significantly. See [CONTRIBUTING.md](CONTRIBUTING.md). + +**Read next (by task)** + +- **Purpose, directories (`/charts`, `/components`, `/example`)** → [docs/agents/repository.md](docs/agents/repository.md) +- **YAML, Helm, Kustomize** → [docs/agents/yaml-helm-kustomize.md](docs/agents/yaml-helm-kustomize.md) +- **What CI runs, required checks, when in doubt** → [docs/agents/ci-and-validation.md](docs/agents/ci-and-validation.md) +- **Releases, tags, and `?ref=`** → [docs/agents/releases.md](docs/agents/releases.md) +- **Branches, PRs, commits, expectations for changes** → [CONTRIBUTING.md](CONTRIBUTING.md) + +**Domain context (operators and consumers):** the root [README.md](README.md) documents RHOSO deployment, ArgoCD conventions (e.g. sync-waves, pinned `?ref=`), and how applications are sliced—it does not define repository editing policy. Use the links above for how to change this repository. \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..cba45da --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,89 @@ +# Contributing + +This document describes how to contribute to this repository. It applies to human contributors and to AI assistants or agent tooling; some sections are written specifically for automated assistants. + +## Branching and pull request rules + +When contributing changes: + +- Perform changes on a **dedicated branch** per logical change set. +- The branch used for a pull request must be **up to date with `main`**: + - If `main` has advanced, rebase before considering the PR ready. +- Group related changes into one PR; avoid mixing unrelated refactors, new features, and fixes. + +For large or risky changes, prefer smaller, incremental PRs that are easier to review and roll back. + +## Commit message conventions and AI attribution + +We use **Conventional Commits** for all commits in this repository. + +### Conventional commit format + +Commit messages must follow: + +- `type(scope): short description` + +Where: + +- `type` is one of the standard types used in this organization (for example: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`). +- `scope` is optional but recommended, and should reflect the affected area (for example: `charts`, `components`, `example`, or a more specific identifier). +- The short description is concise, in lowercase, and completes the sentence: “This commit will …”. + +Use commit bodies to explain **why** the change was made and any important context or trade‑offs. + +Breaking changes must be clearly indicated according to the Conventional Commits specification. + +### AI tool and model footer + +For any commit where an AI assistant or agent contributed significantly to the change (code, YAML, templates, or docs), add a footer to the commit message indicating the AI tool and model used. + +Use a **git trailer‑style footer**. For example: + +- `AI-Tool: ` +- `AI-Model: ` + +Examples of valid footer tokens: + +- `AI-Tool: Claude Workbench` +- `AI-Model: Claude 3.7 Sonnet (2025-08-15)` + +If multiple tools or models were used, you may list multiple `AI-Tool` and `AI-Model` lines. + +When preparing commit messages, agents must: + +- Ensure the main line and any body follow Conventional Commits rules. +- Add the AI attribution footers when relevant. +- Keep the final message consistent and readable for human reviewers. + +## AI assistants and agent tooling + +AI agents must **not** create pull requests on their own initiative. + +Workflow requirements: + +- Agents may: + - Propose changes. + - Modify files in a local working tree or a feature branch. + - Prepare candidate commit messages and PR descriptions as text. +- Agents must **not**: + - Open pull requests in this repository without an explicit human request. + - Push branches to the remote without an explicit human request. + +Human control and review: + +- All changes produced by agents must be reviewed by a human contributor before: + - commits are pushed + - a pull request is opened + +Agents should treat “create PR” as an action that always requires an explicit human instruction (for example, a user explicitly confirming that the changes are ready to be proposed). + +## Expectations for AI-generated changes + +When making changes, AI agents must: + +- Preserve existing behavior unless the change is explicitly intended to alter it. +- Prefer minimal diffs that address the requested change without broad refactors. +- Keep component and chart names, labels, and annotations consistent with existing patterns in this repo. +- Avoid introducing organization‑specific secrets, credentials, or sensitive data into the repository. + +Whenever there is ambiguity about the correct pattern (for example, multiple existing styles in the same directory), agents should align with the most recent and most widely used pattern in that area of the repo. diff --git a/docs/agents/ci-and-validation.md b/docs/agents/ci-and-validation.md new file mode 100644 index 0000000..c8d9f58 --- /dev/null +++ b/docs/agents/ci-and-validation.md @@ -0,0 +1,43 @@ +# CI, validation, and when in doubt + +## Source of truth: GitHub workflows + +The **GitHub Actions workflows** in `.github/workflows/` are the source of truth for required checks. + +Agents must: + +1. Inspect the relevant workflow files before making changes. +2. Derive the exact commands to run (including install steps, working directories, environment variables, and scripts) from those workflows, and mirror them locally when possible rather than inferring checks from memory or generic examples. +3. Treat any failure in those commands as a blocker and fix issues before opening a pull request. + +Do **not** invent new validation commands unless explicitly requested. Prefer to align with the commands defined in existing workflows. + +## Required checks before committing or opening a PR + +Before creating a commit or a pull request, agents must: + +1. Run all applicable validation steps used in CI for this repo: + - Read the workflow files under `.github/workflows/` and determine which jobs and steps apply to the paths or areas you changed. + - Extract and run the same commands those steps invoke (or an equivalent), matching tool versions or invocations where the workflow pins them. +2. Ensure that: + - All tests pass. + - All linters and formatters pass. + - Generated content (if any) is up to date relative to the commands used in this repo (for example, `make generate` or equivalent, if present). + +If a required tool is not available in the current environment, clearly note the missing tool and do not assume the checks passed. + +## When in doubt + +If an agent is unsure about: + +- Which command to run for validation, +- How a particular directory is meant to be used, +- Whether a change might be breaking for downstream consumers, + +Then it should: + +1. Prefer a conservative, minimal change. +2. Add a short comment in the pull request description explaining the uncertainty and the assumptions made. +3. Leave a clear trail in the commit body describing any potentially breaking or controversial choice. + +This helps human reviewers quickly understand what the agent did and why. diff --git a/docs/agents/releases.md b/docs/agents/releases.md new file mode 100644 index 0000000..e9a7243 --- /dev/null +++ b/docs/agents/releases.md @@ -0,0 +1,24 @@ +# Release process and tag management + +This repository uses Git tags to version the catalog. To keep consumers pinned to explicit versions, every time a new tag is created, the tag must be propagated to all relevant references. + +When preparing or finalizing a release: + +1. After creating a new tag (for example `vX.Y.Z`), perform a follow-up commit that updates all version references to use the new tag. +2. Search the **entire repository** for occurrences of `?ref=` that point to content provided by this repository (for example raw GitHub URLs or module references into `openstack-k8s-operators/gitops`). +3. Update all such references to use the new tag instead of the previous value, **even if the previous value was a branch name** (for example, a feature branch used to make CI pass). + +In particular, verify and update any `?ref=` or similar version selectors in: + +- `/example` (all example manifests and configuration files) +- `/charts` (chart values, templates, or helper files that reference this repo) +- Any `README.md` or other documentation files in this repo + +Rules for agents: + +- Do not leave `?ref=` values pointing to older tags or branches once a new release tag is intended to be the default example. +- Prefer pinned, explicit tags over branch names like `main`, `master`, or feature branches in all references to this repository. +- When introducing new examples or references that point to this repository, always use the **current** released tag, not a branch name. +- When checking `?ref=`, treat URLs that contain `openstack-k8s-operators/gitops` as references to this repository. + +If the repository maintainers follow a specific naming scheme for tags (for example, `vMAJOR.MINOR.PATCH`), preserve that scheme and do not invent new formats. diff --git a/docs/agents/repository.md b/docs/agents/repository.md new file mode 100644 index 0000000..2bfe5d7 --- /dev/null +++ b/docs/agents/repository.md @@ -0,0 +1,26 @@ +# Repository purpose, layout, and semantics + +## Repository purpose and scope + +- This repository is a **catalog of reusable GitOps components** for OpenStack on Kubernetes. +- It does **not** define whole clusters or full environment layouts; instead it provides building blocks (Helm charts and kustomize components) that will be consumed by other GitOps repos. + +When you modify this repository, you are changing **reusable building blocks**, not one-off cluster configs. Prefer conservative, backwards‑compatible changes. + +## Directory structure and semantics + +Follow these rules when reading or modifying files: + +- `/charts` + - Contains Helm charts or chart definitions. + - Keep charts **lint‑clean** and compatible with standard Helm tooling. + - Respect existing chart layout and values structure when extending. +- `/components` + - Contains **kustomize components**. + - Treat this as the primary catalog of reusable manifests. + - Content here may be generated by other tooling; keep structure and style consistent. +- `/example` + - Contains examples that demonstrate how to consume the components. + - Use these as references when adding new components, and keep examples in sync with component changes. + +If you introduce new top‑level directories, add a short description in this file and keep the scope narrow and well defined. diff --git a/docs/agents/yaml-helm-kustomize.md b/docs/agents/yaml-helm-kustomize.md new file mode 100644 index 0000000..8fd36e1 --- /dev/null +++ b/docs/agents/yaml-helm-kustomize.md @@ -0,0 +1,32 @@ +# YAML, Helm, and kustomize invariants + +## 3.1 General YAML rules + +For all YAML files in this repository: + +- Files must be **valid YAML** and parse cleanly with standard tooling. +- Each YAML file must include a `---` document header before the first Kubernetes (or kustomize) object. Leading comment lines (for example source-documentation links or notes) may appear **above** that `---`; do not require `---` to be the very first line of the file. +- Prefer one Kubernetes object per file unless an existing pattern in that directory clearly uses multi‑document files. +- Do not embed inline JSON; use proper YAML mappings and sequences. + +Consistency matters: when editing existing YAML, follow the surrounding style (indentation, quoting, key ordering) unless you are explicitly cleaning it up repo‑wide. + +## 3.2 Kubernetes and GitOps assumptions + +- Manifests must be compatible with standard Kubernetes APIs and controllers used by the OpenStack Kubernetes Operators. +- Avoid using `latest` image tags or unpinned versions; prefer pinned tags or digests consistent with existing patterns in this repo. +- Do not introduce cluster‑specific data (hostnames, IPs, secrets) into this repo. Keep it generic and parameterized so consuming GitOps repos can provide environment‑specific values. + +## 3.3 Helm charts (`/charts`) + +When modifying or adding charts: + +- Keep `Chart.yaml` and `values.yaml` well documented and minimal. +- Validate charts using the commands defined in the GitHub Actions workflows for this repository (see those workflows for the exact `helm` or other invocations). +- Avoid breaking changes to values unless strictly necessary; if unavoidable, document the change in chart docs and in commit messages. + +## 3.4 Kustomize components (`/components`, `/example`) + +- Components should be **composable** and reusable across environments. +- Use kustomize conventions consistently (e.g., `kustomization.yaml` naming, `resources` vs `components` vs `patches`). +- Ensure that overlays or examples under `/example` still build successfully after changes.