Merge pull request #9393 from hercules-ci/changelog-d
Automatically compile hand-written release notes with `changelog-d`
(cherry picked from commit 928f0c13414d20c1af88b30bd6700fd730ee0bab)
Change-Id: Ia0685835c52edf185b64dd696b19305746c077e5
This commit is contained in:
parent
d8a293d61d
commit
e8a488236c
10 changed files with 304 additions and 35 deletions
2
.gitignore
vendored
2
.gitignore
vendored
|
|
@ -21,12 +21,14 @@ perl/Makefile.config
|
|||
/doc/manual/language.json
|
||||
/doc/manual/xp-features.json
|
||||
/doc/manual/src/SUMMARY.md
|
||||
/doc/manual/src/SUMMARY-rl-next.md
|
||||
/doc/manual/src/command-ref/new-cli
|
||||
/doc/manual/src/command-ref/conf-file.md
|
||||
/doc/manual/src/command-ref/experimental-features-shortlist.md
|
||||
/doc/manual/src/contributing/experimental-feature-descriptions.md
|
||||
/doc/manual/src/language/builtins.md
|
||||
/doc/manual/src/language/builtin-constants.md
|
||||
/doc/manual/src/release-notes/rl-next.md
|
||||
|
||||
# /scripts/
|
||||
/scripts/nix-profile.sh
|
||||
|
|
|
|||
|
|
@ -92,7 +92,7 @@ $(d)/nix-profiles.5: $(d)/src/command-ref/files/profiles.md
|
|||
$(trace-gen) lowdown -sT man --nroff-nolinks -M section=5 $^.tmp -o $@
|
||||
@rm $^.tmp
|
||||
|
||||
$(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md
|
||||
$(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/SUMMARY-rl-next.md $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md
|
||||
@cp $< $@
|
||||
@$(call process-includes,$@,$@)
|
||||
|
||||
|
|
@ -144,6 +144,24 @@ $(d)/language.json: $(bindir)/nix
|
|||
$(trace-gen) $(dummy-env) NIX_PATH=nix/corepkgs=corepkgs $(bindir)/nix __dump-language > $@.tmp
|
||||
@mv $@.tmp $@
|
||||
|
||||
# Generate "Upcoming release" notes (or clear it and remove from menu)
|
||||
$(d)/src/release-notes/rl-next.md: $(d)/rl-next $(d)/rl-next/*
|
||||
@if type -p changelog-d > /dev/null; then \
|
||||
echo " GEN " $@; \
|
||||
changelog-d doc/manual/rl-next > $@; \
|
||||
else \
|
||||
echo " NULL " $@; \
|
||||
true > $@; \
|
||||
fi
|
||||
|
||||
$(d)/src/SUMMARY-rl-next.md: $(d)/src/release-notes/rl-next.md
|
||||
$(trace-gen) true
|
||||
@if [ -s $< ]; then \
|
||||
echo ' - [Upcoming release](release-notes/rl-next.md)' > $@; \
|
||||
else \
|
||||
true > $@; \
|
||||
fi
|
||||
|
||||
# Generate the HTML manual.
|
||||
.PHONY: manual-html
|
||||
manual-html: $(docdir)/manual/index.html
|
||||
|
|
@ -173,7 +191,7 @@ doc/manual/generated/man1/nix3-manpages: $(d)/src/command-ref/new-cli
|
|||
done
|
||||
@touch $@
|
||||
|
||||
$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md $(d)/src/command-ref/conf-file.md $(d)/src/language/builtins.md $(d)/src/language/builtin-constants.md
|
||||
$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md $(d)/src/command-ref/conf-file.md $(d)/src/language/builtins.md $(d)/src/language/builtin-constants.md $(d)/src/release-notes/rl-next.md
|
||||
$(trace-gen) \
|
||||
tmp="$$(mktemp -d)"; \
|
||||
cp -r doc/manual "$$tmp"; \
|
||||
|
|
|
|||
2
doc/manual/rl-next/config
Normal file
2
doc/manual/rl-next/config
Normal file
|
|
@ -0,0 +1,2 @@
|
|||
organization: NixOS
|
||||
repository: nix
|
||||
9
doc/manual/rl-next/nix-env-json-drv-path.md
Normal file
9
doc/manual/rl-next/nix-env-json-drv-path.md
Normal file
|
|
@ -0,0 +1,9 @@
|
|||
synopsis: Fix `nix-env --query --drv-path --json`
|
||||
prs: #9257
|
||||
description: {
|
||||
|
||||
Fixed a bug where `nix-env --query` ignored `--drv-path` when `--json` was set.
|
||||
|
||||
}
|
||||
|
||||
|
||||
|
|
@ -109,6 +109,7 @@
|
|||
- [CLI guideline](contributing/cli-guideline.md)
|
||||
- [C++ style guide](contributing/cxx.md)
|
||||
- [Release Notes](release-notes/release-notes.md)
|
||||
{{#include ./SUMMARY-rl-next.md}}
|
||||
- [Release 2.18 (2023-09-20)](release-notes/rl-2.18.md)
|
||||
- [Release 2.17 (2023-07-24)](release-notes/rl-2.17.md)
|
||||
- [Release 2.16 (2023-05-31)](release-notes/rl-2.16.md)
|
||||
|
|
|
|||
|
|
@ -285,3 +285,41 @@ can build it yourself:
|
|||
|
||||
Metrics about the change in line/function coverage over time are also
|
||||
[available](https://hydra.nixos.org/job/nix/master/coverage#tabs-charts).
|
||||
|
||||
## Add a release note
|
||||
|
||||
`doc/manual/rl-next` contains release notes entries for all unreleased changes.
|
||||
|
||||
User-visible changes should come with a release note.
|
||||
|
||||
### Add an entry
|
||||
|
||||
Here's what a complete entry looks like. The file name is not incorporated in the document.
|
||||
|
||||
```
|
||||
synopsis: Basically a title
|
||||
issues: #1234
|
||||
prs: #1238
|
||||
description: {
|
||||
|
||||
Here's one or more paragraphs that describe the change.
|
||||
|
||||
- It's markdown
|
||||
- Add references to the manual using @docroot@
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
Significant changes should add the following header, which moves them to the top.
|
||||
|
||||
```
|
||||
significance: significant
|
||||
```
|
||||
|
||||
<!-- Keep an eye on https://codeberg.org/fgaz/changelog-d/issues/1 -->
|
||||
See also the [format documentation](https://github.com/haskell/cabal/blob/master/CONTRIBUTING.md#changelog).
|
||||
|
||||
### Build process
|
||||
|
||||
Releases have a precomputed `rl-MAJOR.MINOR.md`, and no `rl-next.md`.
|
||||
Set `buildUnreleasedNotes = true;` in `flake.nix` to build the release notes on the fly.
|
||||
|
|
|
|||
|
|
@ -1,5 +0,0 @@
|
|||
# Release X.Y (202?-??-??)
|
||||
|
||||
- `nix-shell` shebang lines now support single-quoted arguments.
|
||||
|
||||
- Fixed a bug where `nix-env --query` ignored `--drv-path` when `--json` was set.
|
||||
12
flake.nix
12
flake.nix
|
|
@ -13,6 +13,9 @@
|
|||
|
||||
officialRelease = true;
|
||||
|
||||
# Set to true to build the release notes for the next release.
|
||||
buildUnreleasedNotes = false;
|
||||
|
||||
version = lib.fileContents ./.version + versionSuffix;
|
||||
versionSuffix =
|
||||
if officialRelease
|
||||
|
|
@ -169,6 +172,8 @@
|
|||
"--enable-internal-api-docs"
|
||||
];
|
||||
|
||||
changelog-d = pkgs.buildPackages.changelog-d;
|
||||
|
||||
nativeBuildDeps =
|
||||
[
|
||||
buildPackages.bison
|
||||
|
|
@ -185,7 +190,10 @@
|
|||
buildPackages.mercurial # FIXME: remove? only needed for tests
|
||||
buildPackages.jq # Also for custom mdBook preprocessor.
|
||||
]
|
||||
++ lib.optionals stdenv.hostPlatform.isLinux [(buildPackages.util-linuxMinimal or buildPackages.utillinuxMinimal)];
|
||||
++ lib.optionals stdenv.hostPlatform.isLinux [(buildPackages.util-linuxMinimal or buildPackages.utillinuxMinimal)]
|
||||
# Official releases don't have rl-next, so we don't need to compile a changelog
|
||||
++ lib.optional (!officialRelease && buildUnreleasedNotes) changelog-d
|
||||
;
|
||||
|
||||
buildDeps =
|
||||
[ curl
|
||||
|
|
@ -746,6 +754,8 @@
|
|||
++ lib.optional
|
||||
(stdenv.cc.isClang && stdenv.hostPlatform == stdenv.buildPlatform)
|
||||
pkgs.buildPackages.clang-tools
|
||||
# We want changelog-d in the shell even if the current build doesn't need it
|
||||
++ lib.optional (officialRelease || ! buildUnreleasedNotes) changelog-d
|
||||
;
|
||||
|
||||
buildInputs = buildDeps ++ propagatedDeps
|
||||
|
|
|
|||
179
maintainers/release-notes
Executable file
179
maintainers/release-notes
Executable file
|
|
@ -0,0 +1,179 @@
|
|||
#!/usr/bin/env nix-shell
|
||||
#!nix-shell -i bash ../shell.nix -I nixpkgs=channel:nixos-unstable-small
|
||||
# ^^^^^^^
|
||||
# Only used for bash. shell.nix goes to the flake.
|
||||
|
||||
# --- CONFIGURATION ---
|
||||
|
||||
# This does double duty for
|
||||
# - including rl-next
|
||||
# - marking where to insert new links (right after)
|
||||
SUMMARY_MARKER_LINE='{{#include ./SUMMARY-rl-next.md}}'
|
||||
|
||||
# --- LIB ---
|
||||
|
||||
log() {
|
||||
echo 1>&2 "release-notes:" "$@"
|
||||
}
|
||||
logcmd() {
|
||||
local cmd="$1"
|
||||
shift
|
||||
logcmd2 "$cmd" "${*@Q}" "$cmd" "$@"
|
||||
}
|
||||
logcmd2() {
|
||||
local fakecmd="$1"
|
||||
local fakeargs="$2"
|
||||
shift
|
||||
shift
|
||||
printf 1>&2 "release-notes: \033[34;1m$fakecmd\033[0m "
|
||||
echo "$fakeargs" 1>&2
|
||||
"$@"
|
||||
}
|
||||
die() {
|
||||
# ANSI red
|
||||
printf 1>&2 "release-notes: \033[31;1merror:\033[0m"
|
||||
echo 1>&2 "" "$@"
|
||||
exit 1
|
||||
}
|
||||
confirm() {
|
||||
local answer
|
||||
echo 1>&2 "$@" "[y/n]"
|
||||
read -r answer
|
||||
case "$answer" in
|
||||
y|Y|yes|Yes|YES)
|
||||
return 0
|
||||
;;
|
||||
n|N|no|No|NO)
|
||||
return 1
|
||||
;;
|
||||
*)
|
||||
echo 1>&2 "please answer y or n"
|
||||
confirm "$@"
|
||||
;;
|
||||
esac
|
||||
}
|
||||
report_done() {
|
||||
logcmd2 "git" "show" git -c pager.show=false show
|
||||
printf 1>&2 "release-notes: \033[32;1mdone\033[0m\n"
|
||||
}
|
||||
|
||||
# --- PARSE ARGS ---
|
||||
|
||||
if [[ $# -gt 0 ]]; then
|
||||
die "Release notes takes no arguments, but make sure to set VERSION."
|
||||
fi
|
||||
|
||||
# --- CHECKS ---
|
||||
|
||||
if [[ ! -e flake.nix ]] || [[ ! -e .git ]]; then
|
||||
die "must run in repo root"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# repo must be clean
|
||||
if ! git diff --quiet; then
|
||||
die "repo is dirty, please commit or stash changes"
|
||||
fi
|
||||
|
||||
if ! git diff --quiet --cached; then
|
||||
die "repo has staged changes, please commit or stash them"
|
||||
fi
|
||||
|
||||
if ! grep "$SUMMARY_MARKER_LINE" doc/manual/src/SUMMARY.md.in >/dev/null; then
|
||||
# would have been nice to catch this early, but won't be worth the extra infra
|
||||
die "SUMMARY.md.in is missing the marker line '$SUMMARY_MARKER_LINE', which would be used for inserting a new release notes page. Please fix the script."
|
||||
fi
|
||||
|
||||
if [[ ! -n "${VERSION:-}" ]]; then
|
||||
die "please set the VERSION environment variable before invoking this script"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# version_major_minor: MAJOR.MINOR
|
||||
# version_full: MAJOR.MINOR.PATCH
|
||||
# IS_PATCH: true if this is a patch release; append instead of create
|
||||
if grep -E '^[0-9]+\.[0-9]+$' <<< "$VERSION" >/dev/null; then
|
||||
log 'is minor'
|
||||
IS_PATCH=false
|
||||
version_full="$VERSION.0"
|
||||
version_major_minor="$VERSION"
|
||||
elif grep -E '^[0-9]+\.[0-9]+\.0$' <<< "$VERSION" >/dev/null; then
|
||||
log 'is minor (.0)'
|
||||
IS_PATCH=false
|
||||
version_full="$VERSION"
|
||||
version_major_minor="$(echo "$VERSION" | sed -e 's/\.0$//')"
|
||||
elif grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' <<< "$VERSION" >/dev/null; then
|
||||
log 'is patch'
|
||||
IS_PATCH=true
|
||||
version_full="$VERSION"
|
||||
version_major_minor="$(echo "$VERSION" | sed -e 's/\.[0-9]*$//')"
|
||||
else
|
||||
die "VERSION must be MAJOR.MINOR[.PATCH], where each is a number, e.g. 2.20 or 2.20.1 (VERSION was set to $VERSION)"
|
||||
fi
|
||||
|
||||
unset VERSION
|
||||
|
||||
log "version_major_minor=$version_major_minor"
|
||||
log "version_full=$version_full"
|
||||
log "IS_PATCH=$IS_PATCH"
|
||||
|
||||
basename=rl-${version_major_minor}.md
|
||||
file=doc/manual/src/release-notes/$basename
|
||||
|
||||
if ! $IS_PATCH; then
|
||||
if [[ -e $file ]]; then
|
||||
die "release notes file $file already exists. If you'd like to make a minor release, pass a patch version, e.g. 2.20.1"
|
||||
fi
|
||||
fi
|
||||
|
||||
# --- DEFAULTS ---
|
||||
|
||||
if [[ ! -n "${DATE:-}" ]]; then
|
||||
DATE="$(date +%Y-%m-%d)"
|
||||
log "DATE not set, using $DATE"
|
||||
fi
|
||||
|
||||
case "$DATE" in
|
||||
[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9])
|
||||
;;
|
||||
*)
|
||||
die "DATE must be YYYY-MM-DD, e.g. 2021-12-31 (DATE was set to $DATE)"
|
||||
;;
|
||||
esac
|
||||
|
||||
# --- DO THE WORK ---
|
||||
|
||||
# menu
|
||||
title="Release $version_major_minor ($DATE)"
|
||||
# section on page
|
||||
section_title="Release $version_full ($DATE)"
|
||||
|
||||
(
|
||||
# TODO add minor number, and append?
|
||||
echo "# $section_title"
|
||||
echo
|
||||
changelog-d doc/manual/rl-next | sed -e 's/ *$//'
|
||||
) | tee -a $file
|
||||
|
||||
log "Wrote $file"
|
||||
|
||||
if ! $IS_PATCH; then
|
||||
NEW_SUMMARY_LINE=" - [$title](release-notes/$basename)"
|
||||
|
||||
# find the marker line, insert new link after it
|
||||
escaped_marker="$(echo "$SUMMARY_MARKER_LINE" | sed -e 's/\//\\\//g' -e 's/ /\\ /g')"
|
||||
escaped_line="$(echo "$NEW_SUMMARY_LINE" | sed -e 's/\//\\\//g' -e 's/ /\\ /g')"
|
||||
logcmd sed -i -e "/$escaped_marker/a $escaped_line" doc/manual/src/SUMMARY.md.in
|
||||
fi
|
||||
|
||||
for f in doc/manual/rl-next/*.md; do
|
||||
if [[ config != "$(basename $f)" ]]; then
|
||||
logcmd git rm $f
|
||||
fi
|
||||
done
|
||||
|
||||
logcmd git add $file doc/manual/src/SUMMARY.md.in
|
||||
logcmd git status
|
||||
logcmd git commit -m "release notes: $version_full"
|
||||
|
||||
report_done
|
||||
|
|
@ -24,34 +24,23 @@ release:
|
|||
* In a checkout of the Nix repo, make sure you're on `master` and run
|
||||
`git pull`.
|
||||
|
||||
* Move the contents of `doc/manual/src/release-notes/rl-next.md`
|
||||
(except the first line) to
|
||||
`doc/manual/src/release-notes/rl-$VERSION.md` (where `$VERSION` is
|
||||
the contents of `.version` *without* the patch level, e.g. `2.12`
|
||||
rather than `2.12.0`).
|
||||
|
||||
* Add a header to `doc/manual/src/release-notes/rl-$VERSION.md` like
|
||||
|
||||
```
|
||||
# Release 2.12 (2022-12-06)
|
||||
```
|
||||
|
||||
* Proof-read / edit / rearrange the release notes. Breaking changes
|
||||
and highlights should go to the top.
|
||||
|
||||
* Add a link to the release notes to `doc/manual/src/SUMMARY.md.in`
|
||||
(*not* `SUMMARY.md`), e.g.
|
||||
|
||||
```
|
||||
- [Release 2.12 (2022-12-06)](release-notes/rl-2.12.md)
|
||||
```
|
||||
|
||||
* Run
|
||||
* Compile the release notes by running
|
||||
|
||||
```console
|
||||
$ git checkout -b release-notes
|
||||
$ git add doc/manual/src/release-notes/rl-$VERSION.md
|
||||
$ git commit -a -m 'Release notes'
|
||||
$ VERSION=X.YY ./maintainers/release-notes
|
||||
```
|
||||
|
||||
where `X.YY` is *without* the patch level, e.g. `2.12` rather than ~~`2.12.0`~~.
|
||||
|
||||
A commit is created.
|
||||
|
||||
* Proof-read / edit / rearrange the release notes if needed. Breaking changes
|
||||
and highlights should go to the top.
|
||||
|
||||
* Push.
|
||||
|
||||
```console
|
||||
$ git push --set-upstream $REMOTE release-notes
|
||||
```
|
||||
|
||||
|
|
@ -67,15 +56,17 @@ release:
|
|||
$ git checkout -b $VERSION-maintenance
|
||||
```
|
||||
|
||||
* Mark the release as stable:
|
||||
* Mark the release as official:
|
||||
|
||||
```console
|
||||
$ git cherry-pick f673551e71942a52b6d7ae66af8b67140904a76a
|
||||
$ sed -e 's/officialRelease = false;/officialRelease = true;/' -i flake.nix
|
||||
```
|
||||
|
||||
This removes the link to `rl-next.md` from the manual and sets
|
||||
`officialRelease = true` in `flake.nix`.
|
||||
|
||||
* Commit
|
||||
|
||||
* Push the release branch:
|
||||
|
||||
```console
|
||||
|
|
@ -159,6 +150,30 @@ release:
|
|||
|
||||
## Creating a point release
|
||||
|
||||
* Checkout.
|
||||
|
||||
```console
|
||||
$ git checkout XX.YY-maintenance
|
||||
```
|
||||
|
||||
* Determine the next patch version.
|
||||
|
||||
```console
|
||||
$ export VERSION=XX.YY.ZZ
|
||||
```
|
||||
|
||||
* Update release notes.
|
||||
|
||||
```console
|
||||
$ ./maintainers/release-notes
|
||||
```
|
||||
|
||||
* Push.
|
||||
|
||||
```console
|
||||
$ git push
|
||||
```
|
||||
|
||||
* Wait for the desired evaluation of the maintenance jobset to finish
|
||||
building.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue