134 lines
6.8 KiB
Markdown
134 lines
6.8 KiB
Markdown
<!-- Purpose: Make a repository README concise, accurate, and easy to navigate. -->
|
|
<!-- Scope: Keep essential onboarding in the README, move advanced detail into docs when useful, and verify CI-backed badge claims. -->
|
|
|
|
# Clean up a repository README
|
|
|
|
Apply this task to one repository at a time. Read its local agent instructions,
|
|
README, documentation tree, package metadata, and CI configuration before
|
|
editing. Preserve unrelated work, follow the repository's commit policy, and
|
|
do not push, trigger CI, or publish assets unless explicitly requested.
|
|
|
|
## Establish the documentation contract
|
|
|
|
Treat the repository and its executable configuration as the source of truth.
|
|
Before rewriting prose:
|
|
|
|
1. identify the intended audience and the project's current purpose, support
|
|
status, canonical owner and project name, default branch, and license;
|
|
2. run or otherwise verify the shortest supported install, build, and usage
|
|
path rather than copying stale commands;
|
|
3. locate authoritative contributor, configuration, deployment, release,
|
|
troubleshooting, security, and architecture documentation;
|
|
4. inspect inbound links, relative links, anchors, badges, screenshots, and
|
|
commands so useful references are not silently broken; and
|
|
5. note content that is duplicated, obsolete, speculative, or too detailed for
|
|
first-time readers.
|
|
|
|
Do not invent features, compatibility promises, commands, support channels, or
|
|
publication state. Preserve legally or operationally required notices. Keep
|
|
project-specific terminology where it is meaningful, and explain it before
|
|
using unexplained abbreviations.
|
|
|
|
## README structure
|
|
|
|
Make the README a concise entry point. Prefer this order when it fits the
|
|
project, adapting or omitting sections rather than creating empty headings:
|
|
|
|
1. project title and verified status badges;
|
|
2. one short explanation of what the project does and who it is for;
|
|
3. prerequisites and the smallest working installation or setup path;
|
|
4. a minimal usage example with its expected result;
|
|
5. links to configuration and task-oriented documentation;
|
|
6. development and contribution commands; and
|
|
7. license and support information.
|
|
|
|
Use descriptive link text and relative links for files within the repository.
|
|
Keep heading levels ordered, use one term consistently for each concept, label
|
|
code fences, and keep commands directly runnable from the stated directory.
|
|
Avoid tables of contents for short READMEs, repeated navigation blocks,
|
|
marketing filler, exhaustive option references, and prose that merely restates
|
|
command output.
|
|
|
|
Preserve existing information until it is proven obsolete or has a clear new
|
|
home. A shorter README is not successful if maintainers lose necessary
|
|
operational knowledge.
|
|
|
|
## Advanced documentation
|
|
|
|
Keep the basic install and first-use path in the README. When advanced material
|
|
makes that path hard to scan, move cohesive topics into the repository's
|
|
existing documentation structure. If no suitable structure exists and the
|
|
material justifies a separate page, create a small `docs/` area following the
|
|
project's naming conventions and add an **Advanced** section to the README that
|
|
links directly to each new page.
|
|
|
|
Advanced topics can include architecture, uncommon configuration, production
|
|
deployment, CI internals, release procedures, performance tuning, and detailed
|
|
troubleshooting. Do not move essential prerequisites, safety warnings, or the
|
|
only working example out of the README. Ensure moved pages link back or provide
|
|
enough context to be usable when opened directly. Update all affected relative
|
|
links and avoid creating placeholder pages.
|
|
|
|
## Verify CI-backed badges
|
|
|
|
Determine whether the README is expected to show the current default-branch
|
|
version, test, and coverage badges. Resolve `<asset-origin>`, `<owner>`,
|
|
`<project>`, and `<default-branch>` from the canonical repository and CI
|
|
configuration, not merely from the checkout directory. Check these exact
|
|
public URLs after substitution:
|
|
|
|
```text
|
|
<asset-origin>/coverage/<owner>/<project>/<default-branch>/version.svg
|
|
<asset-origin>/coverage/<owner>/<project>/<default-branch>/test.svg
|
|
<asset-origin>/coverage/<owner>/<project>/<default-branch>/coverage.svg
|
|
```
|
|
|
|
Verification must cover the complete path from generation to publication:
|
|
|
|
- inspect CI and tracked scripts to confirm all three SVGs are generated from
|
|
authoritative version, test, and coverage results;
|
|
- confirm CI validates the files as regular and nonempty, archives exactly the
|
|
intended badges, and publishes them only from the default branch to the path
|
|
represented by the public URLs;
|
|
- check that the default branch, owner, project, filenames, asset mount, and
|
|
public origin agree across CI, scripts, server documentation, and README;
|
|
- if network access is available, request each public URL, require a successful
|
|
response with SVG content, and parse it as XML; distinguish a live but stale
|
|
badge from a missing, invalid, or unpublished badge; and
|
|
- verify badge alt text is meaningful and place the three badge images directly
|
|
below the README title without linking them to a report CI does not retain.
|
|
|
|
Do not treat the presence of a README image URL, a workspace SVG, or an archive
|
|
pattern as proof that CI publishes the badge. Do not claim the public badges are
|
|
live until a successful default-branch build has generated and published all
|
|
three and their public responses have been checked.
|
|
|
|
If the project intentionally provides these badges and the existing pipeline
|
|
is incomplete, make the smallest in-scope correction when it is straightforward
|
|
and verify it. For a missing or materially broken badge pipeline, apply
|
|
[`ci-coverage-badges.task.md`](ci-coverage-badges.task.md) as a separate logical
|
|
change instead of embedding a large CI redesign in the README cleanup. Until
|
|
publication is verified, remove or clearly avoid introducing broken badge
|
|
images and report the exact gap.
|
|
|
|
## Verification
|
|
|
|
Before committing:
|
|
|
|
1. render or preview the README and every new documentation page;
|
|
2. check local links, anchors, image references, and code-block formatting with
|
|
the project's Markdown tooling when available;
|
|
3. run every changed quick-start and development command that is safe and
|
|
locally reproducible, and state which commands could not be exercised;
|
|
4. search for stale references to renamed or moved headings and files;
|
|
5. verify the three badge generation and publication paths as described above,
|
|
recording whether the public URL check was performed or unavailable;
|
|
6. inspect the diff for lost information, accidental reflow, project identifiers
|
|
copied from examples, secrets, and unrelated edits; and
|
|
7. commit the README, any moved documentation, and directly related fixes as
|
|
focused, reviewable changes.
|
|
|
|
Report the final README organization, documentation moved or removed, commands
|
|
and links checked, the status of each expected badge URL, the commit ID, and any
|
|
CI or network verification that remained unavailable.
|