mirror of
https://github.com/0xrsydn/idx-cli.git
synced 2026-11-07 09:45:36 +00:00
0xrsydn
809966925e
Release notes were written by hand on GitHub at tag time, so the contents of a stacked release had to be pieced together from every PR, and output changes that scripts and agents rely on were easy to miss. - CHANGELOG.md backfills every published release (0.2.0 to 0.4.0) from its GitHub notes, verbatim. - A PR adds changes/unreleased/<branch-name>.md instead of editing CHANGELOG.md, so stacked PRs never conflict. changes/README.md gives the sections, including Output Changes for JSON, MCP and error-code changes. - scripts/changelog.sh: `check` validates entries and CHANGELOG.md, `release X.Y.Z` folds the entries into a new section (ordered by PR), and `notes X.Y.Z` prints a section as GitHub release notes. - The release workflow sets the GitHub notes from the tag's section. - New flake check `changelog` runs scripts/changelog-test.sh; both scripts are shellchecked. - Entries for 0.5.0: #73, #74, #75, #78, #79, #80, #81 and this PR. Claude-Session: https://claude.ai/code/session_01RqPPVeVDrnLoP7NUZmLRxY
39 lines
1.8 KiB
Markdown
39 lines
1.8 KiB
Markdown
# Changelog entries
|
|
|
|
Every pull request that changes what users or agents see adds one file here,
|
|
`changes/unreleased/<branch-name>.md`; for example, `fix/mcp-warnings` adds
|
|
`changes/unreleased/mcp-warnings.md`. Each PR has its own file, so stacked PRs
|
|
never conflict over the changelog. Internal refactors, CI-only and test-only
|
|
changes need no entry.
|
|
|
|
An entry holds `### <section>` headings with one bullet per change. Write each
|
|
bullet as one sentence for the user, saying what changed for them, and end it
|
|
with the PR number:
|
|
|
|
```markdown
|
|
### Bug Fixes
|
|
|
|
- `ownership import` reads IDX's register from October 2026 on, which adds a `CONTROLLER_OR_AFFILIATE` column. (#79)
|
|
```
|
|
|
|
The sections, in the order a release lists them:
|
|
|
|
| Section | For |
|
|
| --- | --- |
|
|
| `Security` | vulnerabilities, with what an attacker could do |
|
|
| `New Features` | new commands, tools, flags and providers |
|
|
| `Bug Fixes` | wrong output, crashes, failures |
|
|
| `Improvements` | speed, robustness, help text, distribution |
|
|
| `Output Changes` | any change to JSON fields, MCP results, error codes or exit codes that scripts and agents read; start a breaking one with **Breaking:** |
|
|
| `Docs` | user-facing documentation |
|
|
| `Testing` | what was verified, when a release needs to say so |
|
|
| `Notes` | dependencies, requirements, known limits |
|
|
|
|
A release may add `changes/unreleased/summary.md`: a short paragraph with no
|
|
headings that opens its notes, such as "**Upgrade from 0.3.2**: ...".
|
|
|
|
`scripts/changelog.sh check` (part of `nix flake check`) validates the entries.
|
|
At release time, `scripts/changelog.sh release X.Y.Z` folds them into a new
|
|
section of [`CHANGELOG.md`](../CHANGELOG.md) and deletes them; edit the section
|
|
if needed and commit it with the version bump. The release workflow publishes
|
|
that section as the GitHub release notes.
|