Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 14 additions & 2 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,9 +111,21 @@ echo "✓ Pre-commit hook passed"

### Changelog

Each release crate (`payjoin`, `payjoin-cli`, `payjoin-mailroom`) and `payjoin-ffi` keeps a `CHANGELOG.md` with an `## Unreleased` section at the top. If your pull request changes what a user of that crate sees, add a line there in the same commit. Write it for the person reading the release notes, not for the reviewer. The release PR renames the heading to the version number and nothing else. `payjoin-ffi/CHANGELOG.md` is the release notes for the Python, JavaScript, C# and Dart packages, which are released together at its version.
Each release crate (`payjoin`, `payjoin-cli`, `payjoin-mailroom`) and `payjoin-ffi` keeps a `CHANGELOG.md`. Pull requests don't edit it. If your pull request changes what a user of that crate sees, add a new file to the crate's `changelog.d/` directory in the same commit, such as `payjoin/changelog.d/reject-duplicate-inputs.md`. Give it a name no other pull request is likely to pick, so two pull requests never touch the same file. Write it for the person reading the release notes, not for the reviewer.

If the change has no user-visible effect (refactoring, tests, CI, comments), say so in the pull request description and a maintainer will apply the `changelog: none` label. CI fails a pull request that touches one of those crates' `src/` without either a changelog line or that label.
A fragment must be a visible, regular `.md` file with LF line endings. It holds one or more Markdown list items starting with `- `. Indent continuation lines by at least two spaces or a tab. Blank lines within an item, including paragraphs and indented code blocks, are preserved; spacing between items, headings and fragments is trimmed. Only `### ` headings are allowed at the top level, such as `### API Additions` or `### Bug Fixes`; the release collects every fragment's items under the heading they share.

```markdown
- Reject an Original PSBT that spends the same input twice.

### API Additions

- Add `InputPair::outpoint`.
```

The release PR moves the fragments into the new version's section of `CHANGELOG.md` and deletes them. `payjoin-ffi/CHANGELOG.md` is the release notes for the Python, JavaScript, C# and Dart packages, which are released together at its version. Changes specific to Python, JavaScript or Dart go in `payjoin-ffi/python/changelog.d/`, `payjoin-ffi/javascript/changelog.d/` or `payjoin-ffi/dart/changelog.d/`, respectively. C# changes go in the shared `payjoin-ffi/changelog.d/` directory.

If the change has no user-visible effect (refactoring, tests, CI, comments), say so in the pull request description and a maintainer will apply the `changelog: none` label. CI fails a pull request that touches one of those crates' `src/` without either a fragment or that label.

### Deprecations

Expand Down
18 changes: 12 additions & 6 deletions .github/ISSUE_TEMPLATE/minor-release.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ assignees: ""

Release-managed crates are `payjoin`, `payjoin-cli` and `payjoin-mailroom`. Versions follow
[Semantic Versioning]. Tags are `<crate>-<version>`. The changelog for this release is the
`## Unreleased` section of `CRATE/CHANGELOG.md`; it was written by the pull requests that
landed since the last release, so there is nothing to compile here.
set of fragments in `CRATE/changelog.d/`; each pull request that landed since the last
release wrote its own, so there is nothing to compile here.

### Summary

Expand All @@ -23,8 +23,9 @@ landed since the last release, so there is nothing to compile here.

- [ ] Branch `bump-CRATE-MAJOR-MINOR+1` from `master`.
- [ ] Run `contrib/release/bump.sh CRATE MAJOR.MINOR+1.0`. It sets the version, rewrites
every workspace member's requirement on the crate, renames `## Unreleased` to
`## MAJOR.MINOR+1.0` with a fresh empty `## Unreleased` above it, fills in the
every workspace member's requirement on the crate, moves the fragments in
`CRATE/changelog.d/` into a new `## MAJOR.MINOR+1.0` section of `CRATE/CHANGELOG.md`
and deletes them, fills in the
`0.0.0-unreleased` placeholders in the crate's source, regenerates both lock files
and runs check-invariants. It needs jq, and the lock file step calls
`cargo +nightly`, so run it where rustup has a nightly toolchain. `nix develop .#release`
Expand All @@ -36,8 +37,13 @@ landed since the last release, so there is nothing to compile here.
for `payjoin`, cargo-semver-checks.
- [ ] Merge.

If a fix must land before the tag, merge it to `master` as usual; it carries its own
changelog line. The bump PR is not edited for it.
If a pull request for CRATE merges while the bump PR is open, rebase the bump branch on
`master`, run `contrib/release/bump.sh CRATE MAJOR.MINOR+1.0` again and amend the bump
commit. At a version it already set, bump.sh moves the new fragments into that version's
section and fills in any new placeholders. If one merges after the bump PR and before the
tag, do the same in a new pull request; if that fills in placeholders under `CRATE/src`,
it needs the `changelog: none` label. `tag.sh` refuses to tag while `CRATE/changelog.d/`
holds a fragment.

#### Tag and publish

Expand Down
71 changes: 61 additions & 10 deletions .github/workflows/changelog-check.yml
Original file line number Diff line number Diff line change
@@ -1,9 +1,12 @@
# .github/workflows/changelog-check.yml
#
# A pull request that changes a release crate's or payjoin-ffi's source
# must add a line to that crate's CHANGELOG.md under "## Unreleased", or
# carry the "changelog: none" label. The bump PR then only renames the
# heading, so a merge under an open bump PR never requires editing it.
# must add a changelog fragment in a directory that crate reads, or carry
# the "changelog: none" label. Each pull request writes its own file, so
# pull requests do not conflict over CHANGELOG.md. A bump PR, which
# changes the crate's version, passes by deleting the fragments it moves
# into CHANGELOG.md. Every fragment in the tree must also be one bump.sh
# reads and can parse, since a bad one stops the next release.
name: Changelog

on:
Expand All @@ -16,27 +19,75 @@ permissions:
jobs:
changelog:
name: Changelog entry
if: "${{ !contains(github.event.pull_request.labels.*.name, 'changelog: none') }}"
runs-on: ubuntu-26.04
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false # unneeded: no git auth beyond checkout
fetch-depth: 0
- name: Require a changelog line for each changed crate
- name: Require a changelog fragment for each changed crate
if: "${{ !contains(github.event.pull_request.labels.*.name, 'changelog: none') }}"
env:
BASE: ${{ github.event.pull_request.base.sha }}
HEAD: ${{ github.event.pull_request.head.sha }}
run: |
set -euo pipefail
source contrib/release/crates.sh
changed="$(git diff --name-only "$BASE" "$HEAD")"
mapfile -d '' -t changed < <(git diff --name-only -z "$BASE" "$HEAD")
mapfile -d '' -t written < <(git diff --name-only -z --diff-filter=AMR "$BASE" "$HEAD")
mapfile -d '' -t deleted < <(git diff --name-only -z --diff-filter=D "$BASE" "$HEAD")
has_path() {
local prefix="$1" path
shift
for path in "$@"; do
[[ $path == "$prefix"* ]] && return 0
done
return 1
}
status=0
for crate in $RELEASE_CRATES payjoin-ffi; do
grep -q "^$crate/src/" <<<"$changed" || continue
if ! grep -q "^$crate/CHANGELOG.md$" <<<"$changed"; then
echo "::error::$crate/src changed but $crate/CHANGELOG.md did not; add a line under '## Unreleased', or say in the PR description that there is no user-visible change so a maintainer can label it 'changelog: none'"
status=1
has_path "$crate/src/" "${changed[@]}" || continue
mapfile -t dirs < <(changelog_dirs "$crate")
deleted_fragment=0
for dir in "${dirs[@]}"; do
has_path "$dir/" "${written[@]}" && continue 2
if has_path "$dir/" "${deleted[@]}"; then
deleted_fragment=1
fi
done
# A bump, which changes the crate's version, moves fragments
# into CHANGELOG.md.
old="$(version_at "$BASE" "$crate")"
new="$(version_at "$HEAD" "$crate")"
if [ "$deleted_fragment" -eq 1 ] &&
[ -n "$new" ] && [ "$old" != "$new" ]; then
continue
fi
echo "::error::$crate/src changed but no fragment was added in a supported changelog.d/ directory; add one (see the Changelog section of CONTRIBUTING.md), or say in the PR description that there is no user-visible change so a maintainer can label it 'changelog: none'"
status=1
done
exit "$status"
- name: Check every fragment
run: |
set -euo pipefail
./contrib/release/test-changelog-fragments.sh
source contrib/release/crates.sh
dirs=()
for crate in $RELEASE_CRATES payjoin-ffi; do
mapfile -t -O "${#dirs[@]}" dirs < <(changelog_dirs "$crate")
done
status=0
for dir in "${dirs[@]}"; do
echo "Checking $dir"
./contrib/release/changelog-fragments.sh "$dir" >/dev/null || status=1
done
# bump.sh never releases a fragment kept anywhere else.
while IFS= read -r -d '' path; do
[[ $path =~ (^|/)changelog\.d/ ]] || continue
for dir in "${dirs[@]}"; do
[[ $path == "$dir"/* ]] && continue 2
done
printf '::error::%q is not in a changelog.d directory that bump.sh reads\n' "$path"
status=1
done < <(git ls-files -z)
exit "$status"
Loading
Loading