diff --git a/README.md b/README.md
index 63052a9..205b1a7 100644
--- a/README.md
+++ b/README.md
@@ -1,140 +1,137 @@
-
-
-
-# release-notes
+
+
+
+
+
-Generate release notes for a release based on github labels and closed issues and PR's
+release-notes
-## Installation
+Write release notes for a GitHub repository from the issues and pull requests labelled with the version you are releasing, grouped by their other labels.
-Distributed as a .NET tool so install using the following
+
+
+
+
-```
-dotnet tool install release-notes
-```
+The release notes for elastic/apm-agent-dotnet 1.11.0, from the three pull requests labelled `v1.11.0`. The previous
+release is found on its own:
-On Linux, Windows and macOS/arm64, this resolves to a self-contained native-AOT executable — no
-shared .NET runtime required, and no first-run JIT warmup. Everywhere else, it falls back to a
-framework-dependent build (requires the .NET runtime the tool targets to already be installed).
+```console
+$ release-notes generate elastic apm-agent-dotnet --version 1.11.0 --uncategorized-header "Other changes"
+https://github.com/elastic/apm-agent-dotnet/compare/1.10.0...1.11.0
-## GitHub Action
+## New Features
-```yaml
-- uses: nullean/release-notes@main
- with:
- command: generate
- owner: nullean
- repo: release-notes
- args: --version 1.0.0
-```
+- #1239 Add Cosmos DB support (issue: #1154)
+- #1310 Implement config to ignore the sampled flag in traceparent
-Runs `release-notes` from a pre-built, distroless container (`ghcr.io/nullean/release-notes`) — no .NET
-SDK install needed in the workflow. `command` is one of `generate`, `apply-labels`, `find-previous`,
-`current-version`, or `create-release`; extra flags pass through verbatim via `args`. Linux runners only
-(`ubuntu-latest` and similar) — container actions can't run on Windows or macOS runners.
+## Other changes
-## Container image
+- #1302 Prefer W3C traceparent over elastic-apm-traceparent
+
+### [View the full list of issues and PRs](https://github.com/elastic/apm-agent-dotnet/issues?utf8=%E2%9C%93&q=label%3Av1.11.0)
+```
-`ghcr.io/nullean/release-notes` also works as a general-purpose container, outside GitHub Actions —
-GitLab CI, a local machine without the .NET SDK, anywhere `docker run` works:
+## Install
```sh
-docker run --rm ghcr.io/nullean/release-notes:edge generate nullean release-notes --version 1.0.0 --token "$GITHUB_TOKEN"
+dotnet tool install --global release-notes
```
-Distroless: native-AOT, chiseled `runtime-deps` base, no shell, runs as a non-root user. Tags follow
-`release-notes`'s own releases — `edge` tracks the latest commit on `main`, `latest` and a semver tag
-(e.g. `0.10.0`) follow tagged releases.
+On Linux (x64, arm64), Windows (x64, arm64) and macOS (arm64) this installs a self-contained native-AOT executable: no
+shared .NET runtime, no JIT warm-up. Everywhere else it falls back to a framework-dependent build, which needs the .NET
+runtime installed.
-## Run
+## Quick start
-```bat
-dotnet release-notes --version [options]
+```sh
+release-notes generate nullean my-repo --version 1.2.3 --token "$GITHUB_TOKEN" \
+ --label "bug=Bug Fixes" --label "enhancement=New Features" --output release-notes-VERSION.md
```
-You can omit `dotnet` if you install this as a global tool.
-
-> [!IMPORTANT]
-> Starting from `1.0.0`, every invocation requires an explicit command name (`generate`,
-> `apply-labels`, `find-previous`, `current-version` or `create-release`) — there is no longer a bare
-> `release-notes ...` shorthand for `generate`. `--label` also changes from two tokens
-> (`--label `) to one combined token (`--label =`), and every
-> other flag moves from a single word to kebab-case (e.g. `--oldversion` → `--old-version`). This is a
-> breaking change from earlier `0.x` releases, a side effect of moving off `Argu` (which no longer
-> worked once this tool was AOT-compiled) onto [`Nullean.Argh`](https://github.com/nullean/argh).
-
-```bat
-Usage: release-notes [options]
-
-Commands:
- apply-labels Creates the version and backport labels for the next release.
- create-release Makes sure the tag exists as a release on GitHub, and
- introduces new version labels for the next major/minor/patch.
- current-version Given a search query, finds the current and the next versions
- and prints them on separate lines.
- find-previous Finds and prints the previous release for the given version.
- generate Generates release notes for version from closed GitHub issues
- and PRs, printed to standard out and optionally written to a
- file.
+Every command takes the repository owner and name, then `--version`, and needs the command named:
+
+| Command | What it does |
+|---|---|
+| `generate` | prints the release notes, and writes them to `--output` too when given |
+| `create-release` | creates or updates the GitHub release for the tag, with the `--body` files (repeatable) as its notes, and adds the version labels for the next release |
+| `apply-labels` | adds the version labels for the next major, minor and patch release, and backport labels with `--backport-label-format` |
+| `find-previous` | prints the release before `--version` |
+| `current-version` | prints the current and the next version on separate lines for a `--query`: `M.N` (next patch), `M.x` (next minor) or `main`/`master` (next major) |
+
+```console
+$ release-notes find-previous elastic apm-agent-dotnet --version 1.11.0
+1.10.0
+$ release-notes current-version elastic apm-agent-dotnet --version 1.11.0 --query 1.x
+1.14.1
+1.15.0
```
-Every command takes the same ` ` positionals and shared options:
-
-```bat
-Arguments:
- GitHub repository owner.
- GitHub repository name.
-
-Options:
- --version [required] Version that is being released.
- --token The GitHub token to use. If the issue list is long this may be necessary; defaults to anonymous.
- --old-version The previous version to generate release notes since. Optional; the tool will find the previous release.
- --release-tag-format The release tag format. VERSION is replaced by the actual version. [default: VERSION]
- --release-label-format The release label format. VERSION is replaced by the actual version. [default: vVERSION]
- --backport-label-format The backport label format, e.g. "Backport BRANCH". BRANCH is calculated from the version.
- --format The format in which to print the results: Markdown or AsciiDoc. [default: markdown]
- --uncategorized-header The header to use in the markdown for uncategorized issues/PRs.
- --label [repeatable] Map a GitHub label to a categorization heading, formatted as =. May be given
- more than once. Defaults to bug=Bug Fixes, enhancement=New Features, documentation=Documentation Improvements.
- --output Write the release notes to a file as well as standard out. VERSION is replaced by the actual version.
-```
+Shared options:
+
+| Option | What |
+|---|---|
+| `--token` | the GitHub token; anonymous otherwise, which a long issue list can exhaust |
+| `--label =` | map a label to a section (repeatable); replaces the default `bug=Bug Fixes`, `enhancement=New Features`, `documentation=Documentation Improvements` |
+| `--uncategorized-header` | the heading for issues and pull requests none of the labels match |
+| `--old-version` | the release to start from, instead of the one before `--version` |
+| `--release-tag-format`, `--release-label-format` | how tags (`VERSION`) and version labels (`vVERSION`) are spelled; `VERSION` stands for the version |
+| `--format` | `markdown` (default) or `asciidoc` |
+| `--output` | also write the notes to this file; `VERSION` stands for the version |
-#### Examples
+With `--format asciidoc` nothing goes to standard out: `--output` is a directory, which gets
+`release-notes--generated.asciidoc`, an empty `release-notes--human.asciidoc` for your own words (kept
+if it exists), `release-notes-.asciidoc` including both, and a `release-notes.asciidoc` index of the minor's
+patch releases.
-Generate markdown release notes to standard out (and print to a file with `--output`):
+### GitHub Action
-```bat
-dotnet release-notes generate nullean release-notes --version 1.0.0
+```yaml
+- uses: nullean/release-notes@main
+ with:
+ command: generate
+ owner: nullean
+ repo: my-repo
+ args: --version 1.2.3 --token ${{ secrets.GITHUB_TOKEN }}
```
-Find the previous release for a version:
+The action runs `release-notes ` in the prebuilt, distroless
+`ghcr.io/nullean/release-notes:edge` container, so the workflow needs no .NET SDK. `command` is any of the commands
+above; `args` passes through verbatim. Container actions run on Linux runners only.
-```bat
-dotnet release-notes find-previous nullean release-notes --version 1.0.0
-```
+### Container
-Given a search query (`M.N`, `M.x`, or `master`/`main`), print the current and next version on separate lines:
+The same image works anywhere `docker run` does, such as GitLab CI or a machine without the .NET SDK:
-```bat
-dotnet release-notes current-version nullean release-notes --version 1.0.0 --query master
+```sh
+docker run --rm ghcr.io/nullean/release-notes:edge generate nullean my-repo --version 1.2.3 --token "$GITHUB_TOKEN"
```
-Create the version and backport labels for the next release:
+It is native-AOT on a chiseled `runtime-deps` base, with no shell, running as a non-root user. `edge` tracks the latest
+build of `main`; `latest` and the version tags (for example `0.11.5`) follow releases.
-```bat
-dotnet release-notes apply-labels nullean release-notes --version 1.0.0 --backport-label-format "Backport BRANCH"
-```
+### Upgrading from 0.10 and earlier
-Make sure the tag exists as a release on GitHub, using one or more files for the release body, and
-introduce new version labels for the next major/minor/patch:
+0.11.0 moved the CLI onto [Nullean.Argh](https://github.com/nullean/argh), which is a breaking change:
-```bat
-dotnet release-notes create-release nullean release-notes --version 1.0.0 --body notes.md --body breaking-changes.md --token $GITHUB_TOKEN
-```
+- the command is always named: `release-notes ...` without `generate` no longer works;
+- `--label` takes one `=` token instead of two;
+- every flag is kebab-case (`--oldversion` is now `--old-version`).
-Map GitHub labels to custom categorization headings (replaces the default bug/enhancement/documentation set):
+## Packages
-```bat
-dotnet release-notes generate nullean release-notes --version 1.0.0 --label bug=Bug Fixes --label enhancement=New Features
-```
+The tool ships as one package per platform. Install the root package; the .NET SDK picks the right one.
+
+| Package | What it is | |
+|---|---|---|
+| [`release-notes`](src/release-notes/README.md) | the tool; points the SDK at the package for your platform | [](https://www.nuget.org/packages/release-notes) |
+| `release-notes.` | the native-AOT build for `linux-x64`, `linux-arm64`, `win-x64`, `win-arm64` and `osx-arm64` | [](https://www.nuget.org/packages/release-notes.linux-x64) |
+| `release-notes.any` | the framework-dependent fallback (net8.0, net10.0) for every other platform | [](https://www.nuget.org/packages/release-notes.any) |
+
+## Learn more
+
+- [Releases](https://github.com/nullean/release-notes/releases)
+- [Contributing](https://github.com/nullean/.github/blob/main/CONTRIBUTING.md)
+
+MIT licensed. Copyright Nullean and contributors.
diff --git a/src/release-notes/README.md b/src/release-notes/README.md
index 876b37f..c361fe2 100644
--- a/src/release-notes/README.md
+++ b/src/release-notes/README.md
@@ -1,17 +1,41 @@
# release-notes
+
+
A .NET tool that writes release notes for a GitHub repository from the issues and pull requests labelled with the
version being released (`v1.2.3` by default), grouped into sections by their other labels.
-```bash
+[](https://www.nuget.org/packages/release-notes)
+
+## Install
+
+```sh
dotnet tool install --global release-notes
-release-notes generate nullean my-repo --version 1.2.3 --label "bug=Bug Fixes" --label "enhancement=New Features" \
- --output release-notes-VERSION.md
```
-## Commands
+On Linux (x64, arm64), Windows (x64, arm64) and macOS (arm64) this installs a native-AOT executable from the
+`release-notes.` package; everywhere else it falls back to the framework-dependent `release-notes.any`. Install the
+`release-notes` package itself, not those.
+
+## Quick start
+
+```console
+$ release-notes generate elastic apm-agent-dotnet --version 1.11.0 --uncategorized-header "Other changes"
+https://github.com/elastic/apm-agent-dotnet/compare/1.10.0...1.11.0
+
+## New Features
+
+- #1239 Add Cosmos DB support (issue: #1154)
+- #1310 Implement config to ignore the sampled flag in traceparent
-Every command takes the repository owner and name, then `--version`.
+## Other changes
+
+- #1302 Prefer W3C traceparent over elastic-apm-traceparent
+
+### [View the full list of issues and PRs](https://github.com/elastic/apm-agent-dotnet/issues?utf8=%E2%9C%93&q=label%3Av1.11.0)
+```
+
+Every command takes the repository owner and name, then `--version`:
| Command | What it does |
|---|---|
@@ -23,9 +47,13 @@ Every command takes the repository owner and name, then `--version`.
`--token` authenticates with GitHub (anonymous otherwise, which a long issue list can exhaust). `--label
=` maps a label to a section, and defaults to bug, enhancement and documentation. `--format` is
-`Markdown` or `AsciiDoc`; `--release-tag-format` and `--release-label-format` set how tags and version labels are
+`markdown` or `asciidoc`; `--release-tag-format` and `--release-label-format` set how tags and version labels are
spelled, with `VERSION` standing for the version.
-On Linux, Windows and macOS (arm64) the tool installs as a native-AOT binary; elsewhere it falls back to a
-framework-dependent build. It also runs as a container (`ghcr.io/nullean/release-notes`) and as a GitHub Action: see
-https://github.com/nullean/release-notes.
+It also runs as a GitHub Action (`uses: nullean/release-notes@main`) and as a container
+(`ghcr.io/nullean/release-notes`), both without a .NET SDK.
+
+## Learn more
+
+- Source, GitHub Action and container usage: https://github.com/nullean/release-notes
+- Releases: https://github.com/nullean/release-notes/releases