Skip to content

Commit

Permalink
[doc] update release-process.md and backports section of CONTRIBUTING
Browse files Browse the repository at this point in the history
- Mention which directories contain the respective unsigned tarballs
- Clarify that bitcoin.conf might not need to be updated
- Specify where to put historical release notes if there is already
  something in release-notes.md
- Clarify what exactly is the problem with running guix-codesign more
  than once
- Correct number: 6 codesigned attestations are needed before uploading
  binaries
- Remove scp command which is outdated
- Remove server path which is outdated
- Specify that translations update should happen before branch-off, not
  before each release candidate
- Mention that you should notify lists when RCs are available
- Put "Archive the release notes" as a separate step, since creating the
  github release has a dependency on it.
- Update "bitcoin-dev mailing list" to "bitcoin-dev group"
- Document that maintainers should create PRs to collect backports
  • Loading branch information
glozow committed Apr 4, 2024
1 parent ddf1d72 commit 44c421b
Show file tree
Hide file tree
Showing 2 changed files with 33 additions and 26 deletions.
7 changes: 2 additions & 5 deletions CONTRIBUTING.md
Expand Up @@ -417,11 +417,8 @@ Backporting

Security and bug fixes can be backported from `master` to release
branches.
If the backport is non-trivial, it may be appropriate to open an
additional PR to backport the change, but only after the original PR
has been merged.
Otherwise, backports will be done in batches and
the maintainers will use the proper `Needs backport (...)` labels
Maintainers will do backports in batches and
use the proper `Needs backport (...)` labels
when needed (the original author does not need to worry about it).

A backport should contain the following metadata in the commit body:
Expand Down
52 changes: 31 additions & 21 deletions doc/release-process.md
Expand Up @@ -5,17 +5,17 @@ Release Process

### Before every release candidate

* Update translations see [translation_process.md](https://github.com/bitcoin/bitcoin/blob/master/doc/translation_process.md#synchronising-translations).
* Update release candidate version in `configure.ac` (`CLIENT_VERSION_RC`).
* Update manpages (after rebuilding the binaries), see [gen-manpages.py](https://github.com/bitcoin/bitcoin/blob/master/contrib/devtools/README.md#gen-manpagespy).
* Update bitcoin.conf and commit, see [gen-bitcoin-conf.sh](https://github.com/bitcoin/bitcoin/blob/master/contrib/devtools/README.md#gen-bitcoin-confsh).
* Update bitcoin.conf and commit changes if they exist, see [gen-bitcoin-conf.sh](https://github.com/bitcoin/bitcoin/blob/master/contrib/devtools/README.md#gen-bitcoin-confsh).

### Before every major and minor release

* Update [bips.md](bips.md) to account for changes since the last release.
* Update version in `configure.ac` (don't forget to set `CLIENT_VERSION_RC` to `0`).
* Update manpages (see previous section)
* Write release notes (see "Write the release notes" below).
* Write release notes (see "Write the release notes" below) in doc/release-notes.md. If necessary,
archive the previous release notes as doc/release-notes/release-notes-${VERSION}.md.

### Before every major release

Expand All @@ -28,6 +28,7 @@ Release Process

#### Before branch-off

* Update translations see [translation_process.md](https://github.com/bitcoin/bitcoin/blob/master/doc/translation_process.md#synchronising-translations).
* Update hardcoded [seeds](/contrib/seeds/README.md), see [this pull request](https://github.com/bitcoin/bitcoin/pull/27488) for an example.
* Update the following variables in [`src/kernel/chainparams.cpp`](/src/kernel/chainparams.cpp) for mainnet, testnet, and signet:
- `m_assumed_blockchain_size` and `m_assumed_chain_state_size` with the current size plus some overhead (see
Expand Down Expand Up @@ -161,32 +162,40 @@ Then open a Pull Request to the [guix.sigs repository](https://github.com/bitcoi

### macOS codesigner only: Create detached macOS signatures (assuming [signapple](https://github.com/achow101/signapple/) is installed and up to date with master branch)

In the `guix-build-${VERSION}/output/x86_64-apple-darwin` and `guix-build-${VERSION}/output/arm64-apple-darwin` directories:

tar xf bitcoin-osx-unsigned.tar.gz
./detached-sig-create.sh /path/to/codesign.p12
Enter the keychain password and authorize the signature
signature-osx.tar.gz will be created

### Windows codesigner only: Create detached Windows signatures

In the `guix-build-${VERSION}/output/x86_64-w64-mingw32` directory:

tar xf bitcoin-win-unsigned.tar.gz
./detached-sig-create.sh -key /path/to/codesign.key
Enter the passphrase for the key when prompted
signature-win.tar.gz will be created

### Windows and macOS codesigners only: test code signatures
It is advised to test that the code signature attaches properly prior to tagging by performing the `guix-codesign` step.
However if this is done, once the release has been tagged in the bitcoin-detached-sigs repo, the `guix-codesign` step must be performed again in order for the guix attestation to be valid when compared against the attestations of non-codesigner builds.
However if this is done, once the release has been tagged in the bitcoin-detached-sigs repo, the `guix-codesign` step must be performed again in order for the guix attestation to be valid when compared against the attestations of non-codesigner builds. The directories created by `guix-codesign` will need to be cleared prior to running `guix-codesign` again.

### Windows and macOS codesigners only: Commit the detached codesign payloads

```sh
pushd ./bitcoin-detached-sigs
# checkout the appropriate branch for this release series
rm -rf ./*
# checkout or create the appropriate branch for this release series
git checkout --orphan <branch>
# if you are the macOS codesigner
rm -rf osx
tar xf signature-osx.tar.gz
# if you are the windows codesigner
rm -rf win
tar xf signature-win.tar.gz
git add -A
git commit -m "point to ${VERSION}"
git commit -m "<version>: {osx,win} signature for {rc,final}"
git tag -s "v${VERSION}" HEAD
git push the current branch and new tag
popd
Expand Down Expand Up @@ -216,16 +225,16 @@ popd

Then open a Pull Request to the [guix.sigs repository](https://github.com/bitcoin-core/guix.sigs).

## After 3 or more people have guix-built and their results match
## After 6 or more people have guix-built and their results match

Combine the `all.SHA256SUMS.asc` file from all signers into `SHA256SUMS.asc`:
After verifying signatures, combine the `all.SHA256SUMS.asc` file from all signers into `SHA256SUMS.asc`:

```bash
cat "$VERSION"/*/all.SHA256SUMS.asc > SHA256SUMS.asc
```


- Upload to the bitcoincore.org server (`/var/www/bin/bitcoin-core-${VERSION}/`):
- Upload to the bitcoincore.org server:
1. The contents of each `./bitcoin/guix-build-${VERSION}/output/${HOST}/` directory, except for
`*-debug*` files.

Expand All @@ -241,15 +250,17 @@ cat "$VERSION"/*/all.SHA256SUMS.asc > SHA256SUMS.asc
as save storage space *do not upload these to the bitcoincore.org server,
nor put them in the torrent*.

```sh
find guix-build-${VERSION}/output/ -maxdepth 2 -type f -not -name "SHA256SUMS.part" -and -not -name "*debug*" -exec scp {} user@bitcoincore.org:/var/www/bin/bitcoin-core-${VERSION} \;
```
Wait until all of these files have finished uploading before uploading the SHA256SUMS(.asc) files.

2. The `SHA256SUMS` file

3. The `SHA256SUMS.asc` combined signature file you just created
3. The `SHA256SUMS.asc` combined signature file you just created.

- Create a torrent of the `/var/www/bin/bitcoin-core-${VERSION}` directory such
- After uploading release candidate binaries, notify the bitcoin-core-dev mailing list and
bitcoin-dev group that a release candidate is available for testing. Include a link to the release
notes draft.

- Create a torrent of the directory such
that at the top level there is only one file: the `bitcoin-core-${VERSION}`
directory containing everything else. Name the torrent
`bitcoin-${VERSION}.torrent` (note that there is no `-core-` in this name).
Expand All @@ -265,7 +276,10 @@ cat "$VERSION"/*/all.SHA256SUMS.asc > SHA256SUMS.asc
Also put it into the `optional_magnetlink:` slot in the YAML file for
bitcoincore.org.

- Update other repositories and websites for new version
- Archive the release notes for the new version to `doc/release-notes/release-notes-${VERSION}.md`
(branch `master` and branch of the release).

- Update repositories and websites for new version

- bitcoincore.org blog post

Expand All @@ -286,11 +300,7 @@ cat "$VERSION"/*/all.SHA256SUMS.asc > SHA256SUMS.asc

- Push the snap, see https://github.com/bitcoin-core/packaging/blob/main/snap/local/build.md

- This repo

- Archive the release notes for the new version to `doc/release-notes/` (branch `master` and branch of the release)

- Create a [new GitHub release](https://github.com/bitcoin/bitcoin/releases/new) with a link to the archived release notes
- Create a [new GitHub release](https://github.com/bitcoin/bitcoin/releases/new) with a link to the archived release notes

- Announce the release:

Expand Down

0 comments on commit 44c421b

Please sign in to comment.