Add README cleanup task
This commit is contained in:
parent
3d83737823
commit
b73ef8fc47
13
README.md
13
README.md
|
|
@ -15,6 +15,19 @@ reference it from a project task. The receiving agent must still read that
|
|||
project's own instructions and adapt the brief to its existing CI, tools,
|
||||
metadata, and commit conventions.
|
||||
|
||||
## Task catalog
|
||||
|
||||
- [`add-jenkins.task.md`](tasks/add-jenkins.task.md) adds a maintainable Jenkins
|
||||
pipeline.
|
||||
- [`ci-coverage-badges.task.md`](tasks/ci-coverage-badges.task.md) generates and
|
||||
publishes version, test, and coverage badges.
|
||||
- [`make-release-script.task.md`](tasks/make-release-script.task.md) integrates
|
||||
a safe `rust_realease` wrapper.
|
||||
- [`readme-cleanup.task.md`](tasks/readme-cleanup.task.md) streamlines a README,
|
||||
links advanced documentation, and verifies CI-backed badges.
|
||||
- [`semi-harden-ci.task.md`](tasks/semi-harden-ci.task.md) adds focused Rust
|
||||
dependency security and policy gates.
|
||||
|
||||
## Publishing
|
||||
|
||||
Tasks are private to the repository by default:
|
||||
|
|
|
|||
|
|
@ -0,0 +1,133 @@
|
|||
<!-- 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.
|
||||
Loading…
Reference in New Issue