forked from operations/docs
✨ AGENTS.md: Initial commit for LLM contributor guidance
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 <jwheel@redhat.com>
This commit is contained in:
parent
e93b6e7756
commit
d8e1b85683
GPG key ID:
7748B15FA8FA4C7E
1 changed files with 193 additions and 0 deletions
193
AGENTS.md
Normal file
193
AGENTS.md
Normal file
|
|
@ -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: `<gitmoji> <component>: <summary>`
|
||||
- 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).
|
||||
Loading…
Add table
Add a link
Reference in a new issue