Expand README/Antora/changelog rules; keep established chrome - #4
Open
AMDphreak wants to merge 2 commits into
Open
Expand README/Antora/changelog rules; keep established chrome#4AMDphreak wants to merge 2 commits into
AMDphreak wants to merge 2 commits into
Conversation
…tion notes. Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
|
Bugbot is not enabled for your account, so this pull request was not reviewed. Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs. |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Documentation automation review
Verdict: The rule expansions are consistent, accurate against current org practice, and ready to merge. This PR dogfoods its own README guidance (hub Explore the docs » CTA) and correctly prefers that pattern over a separate Docs shield.
What looks good
- Cross-file alignment —
RULES.md,general/documentation.md,general/creator.md,general/readme-layout.md, andgeneral/antora-docs-sites.mdtell the same story on AsciiDoc defaults, Valentus + Lunr + AI search, one Antora site per org, changelog structure, and README chrome. - README change — Centered Explore the docs » →
https://docs.devcentr.org/agent-rules/matchesreadme-layout.mdand switchyard/readme-template convention. - Deliberate badge policy — Dropping mandatory Docs/CI shields avoids fighting the established for-the-badge contributors/forks/stars/issues row; docs discovery via text CTA is the right org pattern.
- Agent load hints —
general/global.mdnow points agents atantora-docs-sites.mdandreadme-layout.mdwhen those tasks arise. - Hub wiring —
agent-rulesis already listed indev-centr/docsantora-playbook.yml; README/docs URLs are correct.
Gaps to track (not blockers for this PR)
- Changelog dogfooding — This PR strengthens changelog rules but does not add a changelog to this repo. A follow-up PR adds
docs/modules/ROOT/pages/changelog.adocwith backfilled entries from git history. - Hub AI search — Rules now mandate
@antora-supplemental/antora-search-chat, butdev-centr/docsplaybook currently registers only@antora/lunr-extension. A separatedev-centr/docsPR should add the AI search extension (register Lunr first). - Automation template drift — The documentation automation prompt still mentions a
[Docs | Dev-Centr]badge; this PR correctly documents org preference for the text CTA instead. Consider updating the automation template to match.
Coverage
| Area | Codepaths / docs touched |
|---|---|
| README layout | general/readme-layout.md, README.md |
| Antora publishing | general/documentation.md, general/antora-docs-sites.md |
| Changelogs | general/creator.md, RULES.md |
| Agent assembly | RULES.md, general/global.md |
Sent by Cursor Automation: Generate docs
| - If the project uses **Antora**, follow the publishing and layout guidance in the Dev-Centr documentation repository: `dev-centr/devcentr` — see `docs/modules/publishing/pages/antora-deployment.adoc` for deployment-oriented details. | ||
| - **One Antora site per org** that already has a hub (e.g. https://docs.devcentr.org). Do not publish secondary per-repo Antora sites on GitHub Pages. Keep `docs/` in the product repo; **wire** into the hub playbook. See `general/antora-docs-sites.md`. Actively deduplicate when you find errant sites. Does **not** apply to mixtures of different docs systems (Antora + Fumadocs is fine). | ||
| - **One Antora site per org** that already has a hub (e.g. https://docs.devcentr.org). Do not publish secondary per-repo Antora sites on GitHub Pages. Keep `docs/` in the product repo; **wire** into the hub playbook. See `general/antora-docs-sites.md`. Actively deduplicate when you find errant sites. Does **not** apply to mixtures of different docs systems (Antora + Fumadocs is fine). Repo-local `antora-playbook.yml` for **preview/validation CI** is fine if it does **not** publish a second public site. | ||
| - **Search:** Enable `@antora/lunr-extension` on every published Antora site. Add the AI-assisted search/help layer from **`antora-supplemental`** — prefer [`@antora-supplemental/antora-search-chat`](https://github.com/antora-supplemental/antora-search-chat) (Lunr-first Search/Ask omnibox). Related: [`antora-ai-help-extension`](https://github.com/antora-supplemental/antora-ai-help-extension). Register Lunr before wrappers that depend on it. |
There was a problem hiding this comment.
Good addition. Follow-up for dev-centr/docs: the hub antora-playbook.yml currently lists only @antora/lunr-extension under antora.extensions — not antora-search-chat. Rules here will read aspirational until that playbook PR lands. Register Lunr before any wrapper that depends on it.
| - The changelog should contain a timeline with quick summaries and links to very detailed changelogs for each date in a `changelog-details` subfolder that names files by `date - title`. | ||
| - If you add docs afterward, update its changelog structure. | ||
| - Structure: an index page named **changelog** (timeline of dates + short summaries + links) and detail pages under `changelog-details/` named `date - title`. Wire the changelog into the active docs system (Antora nav, etc.) when docs exist. | ||
| - If no changelog exists, **create it** and **backfill** from observed functional changes in git history. Unpack commits when the subject line is too thin. |
There was a problem hiding this comment.
Strong guidance. This repo still lacked a changelog at PR open — a follow-up PR adds changelog.adoc + changelog-details/ backfilled from git history and wires it into nav/README per these rules.
|
|
||
| ## Docs link (org repos) | ||
|
|
||
| For **organization** repositories with a README: include an **Explore the docs »** text link in the centered header (same pattern as `dev-centr/readme-template` / `switchyard`), pointing at the **org docs hub** component URL (e.g. `https://docs.devcentr.org/<component>/`), not a secondary per-repo Pages Antora site. Do **not** add a separate `Docs | Org` shield — that fights the established contributors/forks/stars/issues/(license) chrome. |
There was a problem hiding this comment.
Intentional and correct for Dev-Centr chrome. The documentation automation template still mentions a [Docs | Org] shield badge; this section is the canonical org rule — prefer Explore the docs » text link over an extra shield.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Test plan
general/readme-layout.md— no Docs/CI shield mandates