From d8e1b8568366c2e3f0954097758c9417b629e8b5 Mon Sep 17 00:00:00 2001 From: Justin Wheeler Date: Wed, 6 May 2026 00:09:31 +0200 Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20AGENTS.md:=20Initial=20commit=20for?= =?UTF-8?q?=20LLM=20contributor=20guidance?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This repository is a Fedora Docs site, not a codebase, and LLMs working here need context that differs from typical software projects. AGENTS.md provides that context: repository structure, writing conventions, terminology rules, content guidelines, and process awareness. Key guidance includes the one-sentence-per-line convention, the terminology table enforcing "Operations Architect" / "FOA" over the retired "Program Manager" / "FPgM" title, the two-component Antora layout, and the Pagure-to-Forgejo migration status for links. Modeled after the AGENTS.md in the elections-interviews repository, broadened to cover the full scope of operations documentation. Assisted-by: Claude Opus 4.6 (1M context) Signed-off-by: Justin Wheeler --- AGENTS.md | 193 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b2be8f7 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,193 @@ +# AGENTS.md — Fedora Program Operations Documentation + +This repository is a **documentation repository**, not a codebase. +There is no application code, no build system beyond Antora, and no test suite. +All work here concerns technical writing, documentation accuracy, process documentation, and operational coordination for the Fedora Project. + + +## Repository purpose + +This repository contains the source documentation for [Fedora Program Operations](https://docs.fedoraproject.org/en-US/operations/), published as part of the Fedora Docs website via [Antora](https://antora.org/). + +It covers: +- **Changes process** — Policy, guidance, and rationale for Fedora's release change tracking +- **Elections** — Process documentation for Fedora's elected bodies (Council, FESCo, Mindshare, EPEL) +- **Prioritized bugs** — Nomination, evaluation, and escalation of high-priority bugs +- **Release lifecycle** — Scheduling, branching, Go/No-Go meetings, release day, end-of-life +- **Spins and Labs** — Creation, maintenance, and keepalive processes +- **Operations Architect Guide** — Internal SOPs for the person holding the FOA role + +See `README.md` for build instructions and repository structure. + + +## Key roles + +- **Fedora Operations Architect (FOA)** — Primary owner of this documentation and the processes it describes. + Responsible for release coordination, elections, changes tracking, and Council meeting facilitation. +- **Fedora Community Architect (FCA)** — Backup election wrangler. +- **Fedora Project Leader (FPL)** — Escalation path for prioritized bugs and project-level decisions. + +The FOA role was previously called "Fedora Program Manager" (FPgM). +All documentation has been updated to use the current title. +Do not reintroduce "Program Manager" or "FPgM" — use "Operations Architect" or "FOA". + + +## Repository structure + +This repository contains two Antora components in a single git repo: + +``` +. +├── antora.yml .................. Component descriptor for "operations" +├── site.yml .................... Local preview playbook +├── docsbuilder.sh .............. Build script (podman/docker) +├── modules/ROOT/ +│ ├── nav.adoc ................ Sidebar navigation +│ ├── pages/ .................. Main content pages +│ │ ├── pgm_guide/ ......... Operations Architect's internal guide +│ │ │ └── sop/ ........... Standard Operating Procedures +│ │ └── bugs/ .............. Bugzilla documentation +│ ├── partials/ ............... Reusable content fragments +│ └── assets/images/ ......... Static images +└── releases/ ................... Second Antora component + ├── antora.yml .............. Component descriptor for "releases" + └── modules/ROOT/ + ├── nav.adoc ............ Releases sidebar navigation + └── pages/ .............. Release lifecycle and per-release pages + ├── f1/ through f44/ . Per-release information + └── spins/ .......... Spin creation and maintenance docs +``` + +### Antora component names + +- `operations` — referenced in cross-references as `program_management::` (legacy xref prefix) +- `releases` — referenced in cross-references as `releases::` + +Cross-references to other Fedora Docs components use their component names: +- `fesco::` — FESCo documentation +- `council::` — Fedora Council documentation +- `quick-docs::` — Fedora Quick Docs + + +## Writing conventions + +### One sentence per line + +Use **one sentence per line** in all AsciiDoc (`.adoc`) and Markdown (`.md`) files. +This is also known as *ventilated prose* or *semantic linefeeds*. + +Each sentence starts on its own line. +Do not wrap text at a fixed column width or break sentences across lines. +Consecutive lines within a paragraph render as a single paragraph in the output. + +This convention produces cleaner diffs, prevents paragraph reflows, and makes it easier to reorder, comment out, or review individual sentences. + +### AsciiDoc style + +- Use AsciiDoc syntax, not Markdown, for all `.adoc` files. +- Prefer the attribute-based syntax for admonitions: `TIP:`, `NOTE:`, `WARNING:`, `IMPORTANT:`. +- Use `xref:` for internal cross-references between pages in the same or other Antora components. +- Use `https://` links for external URLs. +- When referencing Fedora governance bodies, use their full names on first mention and abbreviations thereafter (e.g., "Fedora Engineering Steering Committee (FESCo)" then "FESCo"). +- Do not use emojis in documentation files unless explicitly requested. + +### Terminology + +| Use | Do not use | +|---|---| +| Fedora Operations Architect | Fedora Program Manager | +| FOA | FPgM | +| Operations Architect | Program Manager (when referring to the Fedora role) | +| Fedora Program Operations | Fedora Program Management (as an organizational name) | + +"Program management" as a general discipline name is acceptable (e.g., "responsible for program management"). + +### Links and cross-references + +Fedora infrastructure is migrating from Pagure to Forgejo. +When adding or updating links: +- Use `https://forge.fedoraproject.org/` for repositories that have migrated (e.g., council tickets, operations docs) +- Use `https://pagure.io/` for repositories that have not yet migrated (e.g., fedora-pgm/schedule, fesco, releng) +- Do not assume a repository has migrated without checking + + +## Content guidelines + +### Accuracy over brevity + +This is governance documentation. +The SOPs define how Fedora releases are coordinated, elections are run, and changes are tracked. +Inaccuracy in these documents can cause real procedural failures. +When in doubt, be precise. + +### Historical references + +Some pages contain historical context (e.g., "Ben Cotton stopped doing X", TaskJuggler references). +These are acceptable as historical notes but should be clearly framed as such. +Do not present historical practices as current procedures. + +### Contact information + +When documentation references specific people by name: +- Verify the person still holds the referenced role before adding or updating names +- Use the format: `https://fedoraproject.org/wiki/User:FASUsername[Display Name]` for wiki links +- For email addresses in public documentation, use the obfuscated format: `username AT domain DOT com` + +### External system references + +Several SOPs reference external systems (Bugzilla, WordPress, Smartsheet, Product Pages). +These are described as they are — do not remove references to proprietary tools that are genuinely used in the process. + + +## Per-release pages + +The `releases/modules/ROOT/pages/` directory contains per-release pages for every Fedora version (F1 through F44). +Each release has an `index.adoc` with release-specific information. +Recent releases (F34+) also have `blocking.adoc` and `spins.adoc` files. + +When a new Fedora release is created: +1. Create a new directory `fNN/` with `index.adoc`, `blocking.adoc`, and `spins.adoc` +2. Update `releases/modules/ROOT/nav.adoc` to add the release under "Upcoming Releases" +3. Move previous releases between "Upcoming", "Supported", and "EOL" sections as appropriate + + +## Commit conventions + +Follow the commit message format described in the project's `CLAUDE.md` or global contributor guidelines: +- Subject: ` : ` +- Body: Explain the reasoning and context behind the change +- Trailer: `Assisted-by:` line per Fedora AI-Assisted Contributions Policy if AI tools were used +- All commits must be GPG-signed with `--signoff` +- Never write `Signed-off-by` manually in the commit message body — the `--signoff` flag adds this trailer automatically + + +## Building locally + +```bash +./docsbuilder.sh +``` + +Requires `podman` (Fedora/Linux) or `docker` (macOS/Windows). +The result is available at `http://localhost:8080`. + +For full Fedora Docs context (checking cross-references to other components), clone the [docs-fp-o](https://pagure.io/fedora-docs/docs-fp-o.git) build repo and point its `site.yml` at your local checkout. + + +## Privacy constraints + +Some SOPs reference private infrastructure (e.g., private election interview issues, Red Hat internal tools like Smartsheet and Product Pages). +Do not add credentials, private URLs, or internal-only information to this repository. +When documenting processes that involve private systems, describe the workflow without exposing access details. + + +## Related repositories + +- [elections-interviews](https://pagure.io/fedora-pgm/elections-interviews) — Private interview submissions for Fedora elections +- [schedule](https://pagure.io/fedora-pgm/schedule) — Release schedule XML files and publishing tools +- [pgm_scripts](https://pagure.io/fedora-pgm/pgm_scripts) — Automation scripts (e.g., inactive provenpackager audit, Bugzilla branching) +- [pgm_communication](https://pagure.io/fedora-pgm/pgm_communication) — Templates for Friday's Fedora Facts, blocker reports, meeting scripts + + +## License + +All content in this repository is licensed under [CC BY-SA 4.0](LICENSE.txt).