Skip to content

Give the README and package READMEs the shared nullean shape - #45

Merged
Mpdreamz merged 1 commit into
mainfrom
docs/readme-standard
Nov 11, 2026
Merged

Mpdreamz merged 1 commit into
mainfrom
docs/readme-standard

Conversation

@Mpdreamz

Copy link
Copy Markdown
Contributor

Brings the root README and the package README in line with the shared nullean templates (standards/README.template.md, standards/PACKAGE-README.template.md, rollout section 6).

Prompt summary: root and package READMEs share common branding and structure; package READMEs are valid for nuget.org; images where they show something off.

What

  • Root README: org lockup (the repository has no logo of its own), tagline, one badge row (NuGet, CI; no docs site). The show-off is the real output of release-notes generate elastic apm-agent-dotnet --version 1.11.0, a public repository that still labels its pull requests vX.Y.Z. After it come install, a quick start with the commands (real find-previous / current-version output), the shared options, the GitHub Action and container usage, upgrade notes, a packages table (root, per-RID, any) and links.
  • Package README (src/release-notes/README.md, packed into the root, any and per-RID packages): follows the package template. It is CommonMark only, with absolute links and the PNG lockup from raw.githubusercontent.com. The quick start is the same real output.
  • Corrected: the upgrade note said the Argh CLI arrived in 1.0.0. It shipped in 0.11.0 (git tag --contains e93d1a4), and nuget.org is at 0.11.5.
  • Now documented:
    • --format asciidoc prints nothing to standard out. --output becomes a directory with the generated, human, per-version and index .asciidoc files (WriteAsciiDocReleaseNotes).
    • create-release is an upsert (CreateOrUpdateRelease).

Verify

Run locally rather than on CI. mise run pack produced the root and any packages. dotnet pack -r osx-arm64 produced a per-RID package the same way CI's aot-pack job does. All three carry a README byte-identical to src/release-notes/README.md.

$ ~/Projects/nullean-dotgithub/scripts/check-package-readme.sh build/output/*.nupkg <rid-out>/*.nupkg
release-notes.0.11.6-canary.0.2.nupkg: ok
release-notes.any.0.11.6-canary.0.2.nupkg: ok
release-notes.osx-arm64.0.11.6-canary.0.2.nupkg: ok

mise run check passes (curb: no drift; zizmor: no findings).

🤖 Generated with Claude Code

The root README gets the org lockup, a tagline, one badge row, the real
release notes the tool generates for elastic/apm-agent-dotnet 1.11.0,
install, quick start with the commands and shared options, the GitHub
Action and container usage, the upgrade notes, a packages table and links.
The package README, packed into the root, any and per-RID packages, follows
the package template and stays nuget.org-safe.

Corrects the upgrade note: the Argh CLI shipped in 0.11.0, not 1.0.0. Adds
what --format asciidoc does: --output becomes a directory and nothing is
printed to standard out.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@Mpdreamz Mpdreamz added the documentation Documentation only (patch) label Nov 11, 2026
@Mpdreamz
Mpdreamz merged commit c5104fe into main Nov 11, 2026
6 checks passed
@Mpdreamz
Mpdreamz deleted the docs/readme-standard branch November 11, 2026 21:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Documentation only (patch)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant