| name | blocks-release-notes |
| description | Generate the release notes for the latest tag of this project. Use after a release tag has just been created to produce a CHANGELOG-<version>.md file describing the changes since the previous tag, written from the user's point of view. |
Release notes
Generate a release-notes file for the most recent release tag of this repository.
When to use
Run this after creating the tag for a new release (e.g. v0.7.0). The skill
diffs the new tag against the previous one and writes the notes to a file.
Steps
-
Find the two tags. Do not hardcode any version — always resolve them from git.
- Latest tag (the one just created): the most recent tag by creation date.
- Previous tag: the tag immediately before it.
LATEST=$(git tag --sort=-creatordate | head -1)
PREV=$(git tag --sort=-creatordate | sed -n '2p')
If there is no previous tag, use the repository's first commit as the lower bound.
-
Collect the changes between the two tags. Read the commit messages and,
when a message is not self-explanatory, the diff stat to understand what
actually changed.
git log --stat "$PREV".."$LATEST"
-
Write the notes to a file named CHANGELOG-<version>.md in the docs
directory, where <version> is the latest tag without the leading v
(e.g. tag v0.7.0 → file docs/CHANGELOG-0.7.0.md).
Output file format
- The top heading states the range, using the previous and the latest tag:
# Changes from <PREV> to <LATEST> (e.g. # Changes from v0.6.1 to v0.7.0).
- Group entries under the sections that apply — omit a section if it is empty:
## New Features## Improvements## Bug Fixes
- Each entry is a bullet. Start a feature/improvement with a short bold lead-in,
followed by an em dash and the description.
Writing style
- English.
- User's point of view. Describe what the change does for the person using
the tool, not how it is implemented. Avoid internal details such as source-file
names, JSON keys, class names or config file names unless they are part of the
CLI the user actually types.
- Impersonal voice. Do not address the reader with "you can …"; phrase things
impersonally (e.g. "the selection can be changed with …", "a workspace can now
target …").
- Keep it concise: one bullet per user-visible change. Merge a release/version-bump
commit into the others — it is not a change on its own.
Example
A well-formed result. Note how implementation-only changes are dropped (a commit
that only refactors internals into a typed class is not a user-visible change),
and how internal names are replaced with what the user perceives:
# Changes from v0.6.1 to v0.7.0
## New Features
- **IDE experts from scripts** — manifest scripts gain two new commands:
`compile`, to build an additional project, and `expert`, which compiles a
package and registers it as a design-time IDE expert. Experts are unregistered
automatically on uninstall.
- **POSIX & Apple platforms** — multi-platform packages now build, install and
uninstall cleanly on POSIX targets (including OSX64) and on Apple platforms
(macOS/iOS), where the correct platform binary is produced.
- **Custom package location** — a package can declare the folder it lives in, so
it no longer has to sit at the repository root.
- **`$(VAR)` macro syntax** — script arguments support the new `$(VAR)` macro
form; the older `%VAR%` syntax keeps working for backward compatibility.
## Improvements
- **Per-platform library paths** — the package's `.dcp` search path is now
registered for every configured platform, not just Win32/Win64.
- **Cleaner uninstall** — uninstall now skips platforms that cannot be built and
removes the package's compiled output.
## Bug Fixes
- Corrected the list of POSIX platforms (OSX64 is now included).
- POSIX packages are now uninstalled correctly.
- Packages without a description no longer fail to register; they show as
`(Untitled)`.
