Skip to content

Commit 318c607

Browse files
dongcarldongcarl
committed
guix: Adapt release-process.md to new Guix process
Also, clean up release-process.md
1 parent fcab35b commit 318c607

File tree

1 file changed

+98
-165
lines changed

1 file changed

+98
-165
lines changed

‎doc/release-process.md

Lines changed: 98 additions & 165 deletions
Original file line numberDiff line numberDiff line change
@@ -38,10 +38,6 @@ Release Process
3838
that causes rejection of blocks in the past history.
3939
- Clear the release notes and move them to the wiki (see "Write the release notes" below).
4040

41-
#### After branch-off (on master)
42-
43-
- Update the version of `contrib/gitian-descriptors/*.yml`.
44-
4541
#### After branch-off (on the major release branch)
4642

4743
- Update the versions.
@@ -64,14 +60,14 @@ This will perform a few last-minute consistency checks in the build system files
6460

6561
### First time / New builders
6662

67-
If you're using the automated script (found in [contrib/gitian-build.py](/contrib/gitian-build.py)), then at this point you should run it with the "--setup" command. Otherwise ignore this.
63+
Install Guix using one of the installation methods detailed in
64+
[contrib/guix/INSTALL.md](/contrib/guix/INSTALL.md).
6865

6966
Check out the source code in the following directory hierarchy.
7067

7168
cd /path/to/your/toplevel/build
72-
git clone https://github.com/bitcoin-core/gitian.sigs.git
69+
git clone https://github.com/bitcoin-core/guix.sigs.git
7370
git clone https://github.com/bitcoin-core/bitcoin-detached-sigs.git
74-
git clone https://github.com/devrandom/gitian-builder.git
7571
git clone https://github.com/bitcoin/bitcoin.git
7672

7773
### Write the release notes
@@ -86,110 +82,56 @@ Generate list of authors:
8682

8783
git log --format='- %aN' v(current version, e.g. 0.20.0)..v(new version, e.g. 0.20.1) | sort -fiu
8884

89-
### Setup and perform Gitian builds
90-
91-
If you're using the automated script (found in [contrib/gitian-build.py](/contrib/gitian-build.py)), then at this point you should run it with the "--build" command. Otherwise ignore this.
92-
93-
Setup Gitian descriptors:
94-
95-
pushd ./bitcoin
96-
export SIGNER="(your Gitian key, ie bluematt, sipa, etc)"
97-
export VERSION=(new version, e.g. 0.20.0)
98-
git fetch
99-
git checkout v${VERSION}
100-
popd
101-
102-
Ensure your gitian.sigs are up-to-date if you wish to gverify your builds against other Gitian signatures.
103-
104-
pushd ./gitian.sigs
105-
git pull
106-
popd
107-
108-
Ensure gitian-builder is up-to-date:
109-
110-
pushd ./gitian-builder
111-
git pull
112-
popd
113-
114-
### Fetch and create inputs: (first time, or when dependency versions change)
115-
116-
pushd ./gitian-builder
117-
mkdir -p inputs
118-
wget -O inputs/osslsigncode-2.0.tar.gz https://github.com/mtrojnar/osslsigncode/archive/2.0.tar.gz
119-
echo '5a60e0a4b3e0b4d655317b2f12a810211c50242138322b16e7e01c6fbb89d92f inputs/osslsigncode-2.0.tar.gz' | sha256sum -c
120-
popd
121-
122-
Create the macOS SDK tarball, see the [macdeploy instructions](/contrib/macdeploy/README.md#deterministic-macos-dmg-notes) for details, and copy it into the inputs directory.
123-
124-
### Optional: Seed the Gitian sources cache and offline git repositories
125-
126-
NOTE: Gitian is sometimes unable to download files. If you have errors, try the step below.
127-
128-
By default, Gitian will fetch source files as needed. To cache them ahead of time, make sure you have checked out the tag you want to build in bitcoin, then:
129-
130-
pushd ./gitian-builder
131-
make -C ../bitcoin/depends download SOURCES_PATH=`pwd`/cache/common
132-
popd
133-
134-
Only missing files will be fetched, so this is safe to re-run for each build.
135-
136-
NOTE: Offline builds must use the --url flag to ensure Gitian fetches only from local URLs. For example:
85+
### Setup and perform Guix builds
13786

138-
pushd ./gitian-builder
139-
./bin/gbuild --url bitcoin=/path/to/bitcoin,signature=/path/to/sigs {rest of arguments}
140-
popd
87+
Checkout the Bitcoin Core version you'd like to build:
14188

142-
The gbuild invocations below <b>DO NOT DO THIS</b> by default.
89+
```sh
90+
pushd ./bitcoin
91+
SIGNER='(your builder key, ie bluematt, sipa, etc)'
92+
VERSION='(new version without v-prefix, e.g. 0.20.0)'
93+
git fetch "v${VERSION}"
94+
git checkout "v${VERSION}"
95+
popd
96+
```
14397

144-
### Build and sign Bitcoin Core for Linux, Windows, and macOS:
98+
Ensure your guix.sigs are up-to-date if you wish to `guix-verify` your builds
99+
against other `guix-attest` signatures.
145100

146-
pushd ./gitian-builder
147-
./bin/gbuild --num-make 2 --memory 3000 --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-linux.yml
148-
./bin/gsign --signer "$SIGNER" --release ${VERSION}-linux --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-linux.yml
149-
mv build/out/bitcoin-*.tar.gz build/out/src/bitcoin-*.tar.gz ../
101+
```sh
102+
git -C ./guix.sigs pull
103+
```
150104

151-
./bin/gbuild --num-make 2 --memory 3000 --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-win.yml
152-
./bin/gsign --signer "$SIGNER" --release ${VERSION}-win-unsigned --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-win.yml
153-
mv build/out/bitcoin-*-win-unsigned.tar.gz inputs/bitcoin-win-unsigned.tar.gz
154-
mv build/out/bitcoin-*.zip build/out/bitcoin-*.exe ../
105+
### Create the macOS SDK tarball: (first time, or when SDK version changes)
155106

156-
./bin/gbuild --num-make 2 --memory 3000 --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-osx.yml
157-
./bin/gsign --signer "$SIGNER" --release ${VERSION}-osx-unsigned --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-osx.yml
158-
mv build/out/bitcoin-*-osx-unsigned.tar.gz inputs/bitcoin-osx-unsigned.tar.gz
159-
mv build/out/bitcoin-*.tar.gz build/out/bitcoin-*.dmg ../
160-
popd
107+
Create the macOS SDK tarball, see the [macdeploy
108+
instructions](/contrib/macdeploy/README.md#deterministic-macos-dmg-notes) for
109+
details.
161110

162-
Build output expected:
111+
### Build and attest to build outputs:
163112

164-
1. source tarball (`bitcoin-${VERSION}.tar.gz`)
165-
2. linux 32-bit and 64-bit dist tarballs (`bitcoin-${VERSION}-linux[32|64].tar.gz`)
166-
3. windows 32-bit and 64-bit unsigned installers and dist zips (`bitcoin-${VERSION}-win[32|64]-setup-unsigned.exe`, `bitcoin-${VERSION}-win[32|64].zip`)
167-
4. macOS unsigned installer and dist tarball (`bitcoin-${VERSION}-osx-unsigned.dmg`, `bitcoin-${VERSION}-osx64.tar.gz`)
168-
5. Gitian signatures (in `gitian.sigs/${VERSION}-<linux|{win,osx}-unsigned>/(your Gitian key)/`)
113+
Follow the relevant Guix README.md sections:
114+
- [Performing a build](/contrib/guix/README.md#performing-a-build)
115+
- [Attesting to build outputs](/contrib/guix/README.md#attesting-to-build-outputs)
169116

170-
### Verify other gitian builders signatures to your own. (Optional)
117+
### Verify other builders' signatures to your own. (Optional)
171118

172119
Add other builders keys to your gpg keyring, and/or refresh keys: See `../bitcoin/contrib/builder-keys/README.md`.
173120

174-
Verify the signatures
175-
176-
pushd ./gitian-builder
177-
./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-linux ../bitcoin/contrib/gitian-descriptors/gitian-linux.yml
178-
./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-win-unsigned ../bitcoin/contrib/gitian-descriptors/gitian-win.yml
179-
./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-osx-unsigned ../bitcoin/contrib/gitian-descriptors/gitian-osx.yml
180-
popd
121+
Follow the relevant Guix README.md sections:
122+
- [Verifying build output attestations](/contrib/guix/README.md#verifying-build-output-attestations)
181123

182124
### Next steps:
183125

184-
Commit your signature to gitian.sigs:
126+
Commit your signature to guix.sigs:
185127

186-
pushd gitian.sigs
187-
git add ${VERSION}-linux/"${SIGNER}"
188-
git add ${VERSION}-win-unsigned/"${SIGNER}"
189-
git add ${VERSION}-osx-unsigned/"${SIGNER}"
190-
git commit -m "Add ${VERSION} unsigned sigs for ${SIGNER}"
191-
git push # Assuming you can push to the gitian.sigs tree
192-
popd
128+
```sh
129+
pushd ./guix.sigs
130+
git add "${VERSION}/${SIGNER}"/noncodesigned.SHA256SUMS{,.asc}
131+
git commit -m "Add ${VERSION} unsigned sigs for ${SIGNER}"
132+
git push # Assuming you can push to the guix.sigs tree
133+
popd
134+
```
193135

194136
Codesigner only: Create Windows/macOS detached signatures:
195137
- Only one person handles codesigning. Everyone else should skip to the next step.
@@ -201,7 +143,7 @@ Codesigner only: Sign the macOS binary:
201143
tar xf bitcoin-osx-unsigned.tar.gz
202144
./detached-sig-create.sh -s "Key ID"
203145
Enter the keychain password and authorize the signature
204-
Move signature-osx.tar.gz back to the gitian host
146+
Move signature-osx.tar.gz back to the guix-build host
205147

206148
Codesigner only: Sign the windows binaries:
207149

@@ -212,93 +154,84 @@ Codesigner only: Sign the windows binaries:
212154

213155
Codesigner only: Commit the detached codesign payloads:
214156

215-
cd ~/bitcoin-detached-sigs
216-
checkout the appropriate branch for this release series
217-
rm -rf *
218-
tar xf signature-osx.tar.gz
219-
tar xf signature-win.tar.gz
220-
git add -A
221-
git commit -m "point to ${VERSION}"
222-
git tag -s v${VERSION} HEAD
223-
git push the current branch and new tag
157+
```sh
158+
pushd ./bitcoin-detached-sigs
159+
# checkout the appropriate branch for this release series
160+
rm -rf ./*
161+
tar xf signature-osx.tar.gz
162+
tar xf signature-win.tar.gz
163+
git add -A
164+
git commit -m "point to ${VERSION}"
165+
git tag -s "v${VERSION}" HEAD
166+
git push the current branch and new tag
167+
popd
168+
```
224169

225170
Non-codesigners: wait for Windows/macOS detached signatures:
226171

227172
- Once the Windows/macOS builds each have 3 matching signatures, they will be signed with their respective release keys.
228173
- Detached signatures will then be committed to the [bitcoin-detached-sigs](https://github.com/bitcoin-core/bitcoin-detached-sigs) repository, which can be combined with the unsigned apps to create signed binaries.
229174

230-
Create (and optionally verify) the signed macOS binary:
175+
Create (and optionally verify) the codesigned outputs:
231176

232-
pushd ./gitian-builder
233-
./bin/gbuild -i --commit signature=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-osx-signer.yml
234-
./bin/gsign --signer "$SIGNER" --release ${VERSION}-osx-signed --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-osx-signer.yml
235-
./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-osx-signed ../bitcoin/contrib/gitian-descriptors/gitian-osx-signer.yml
236-
mv build/out/bitcoin-osx-signed.dmg ../bitcoin-${VERSION}-osx.dmg
237-
popd
177+
- [Codesigning](/contrib/guix/README.md#codesigning)
238178

239-
Create (and optionally verify) the signed Windows binaries:
179+
Commit your signature for the signed macOS/Windows binaries:
240180

241-
pushd ./gitian-builder
242-
./bin/gbuild -i --commit signature=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-win-signer.yml
243-
./bin/gsign --signer "$SIGNER" --release ${VERSION}-win-signed --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-win-signer.yml
244-
./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-win-signed ../bitcoin/contrib/gitian-descriptors/gitian-win-signer.yml
245-
mv build/out/bitcoin-*win64-setup.exe ../bitcoin-${VERSION}-win64-setup.exe
246-
popd
181+
```sh
182+
pushd ./guix.sigs
183+
git add "${VERSION}/${SIGNER}"/all.SHA256SUMS{,.asc}
184+
git commit -m "Add ${SIGNER} ${VERSION} signed binaries signatures"
185+
git push # Assuming you can push to the guix.sigs tree
186+
popd
187+
```
247188

248-
Commit your signature for the signed macOS/Windows binaries:
189+
### After 3 or more people have guix-built and their results match:
249190

250-
pushd gitian.sigs
251-
git add ${VERSION}-osx-signed/"${SIGNER}"
252-
git add ${VERSION}-win-signed/"${SIGNER}"
253-
git commit -m "Add ${SIGNER} ${VERSION} signed binaries signatures"
254-
git push # Assuming you can push to the gitian.sigs tree
255-
popd
191+
Combine `all.SHA256SUMS` and `all.SHA256SUMS.asc` into a clear-signed
192+
`SHA256SUMS.asc` message:
256193

257-
### After 3 or more people have gitian-built and their results match:
194+
```sh
195+
echo -e "-----BEGIN PGP SIGNED MESSAGE-----\nHash: SHA256\n\n$(cat all.SHA256SUMS)\n$(cat filename.txt.asc)" > SHA256SUMS.asc
196+
```
258197

259-
- Create `SHA256SUMS.asc` for the builds, and GPG-sign it:
198+
Here's an equivalent, more readable command if you're confident that you won't
199+
mess up whitespaces when copy-pasting:
260200

261201
```bash
262-
sha256sum * > SHA256SUMS
263-
```
202+
cat << EOF > SHA256SUMS.asc
203+
-----BEGIN PGP SIGNED MESSAGE-----
204+
Hash: SHA256
264205
265-
The list of files should be:
266-
```
267-
bitcoin-${VERSION}-aarch64-linux-gnu.tar.gz
268-
bitcoin-${VERSION}-arm-linux-gnueabihf.tar.gz
269-
bitcoin-${VERSION}-riscv64-linux-gnu.tar.gz
270-
bitcoin-${VERSION}-x86_64-linux-gnu.tar.gz
271-
bitcoin-${VERSION}-osx64.tar.gz
272-
bitcoin-${VERSION}-osx.dmg
273-
bitcoin-${VERSION}.tar.gz
274-
bitcoin-${VERSION}-win64-setup.exe
275-
bitcoin-${VERSION}-win64.zip
206+
$(cat all.SHA256SUMS)
207+
$(cat all.SHA256SUMS.asc)
208+
EOF
276209
```
277-
The `*-debug*` files generated by the gitian build contain debug symbols
278-
for troubleshooting by developers. It is assumed that anyone that is interested
279-
in debugging can run gitian to generate the files for themselves. To avoid
280-
end-user confusion about which file to pick, as well as save storage
281-
space *do not upload these to the bitcoincore.org server, nor put them in the torrent*.
282210

283-
- GPG-sign it, delete the unsigned file:
284-
```
285-
gpg --digest-algo sha256 --clearsign SHA256SUMS # outputs SHA256SUMS.asc
286-
rm SHA256SUMS
287-
```
288-
(the digest algorithm is forced to sha256 to avoid confusion of the `Hash:` header that GPG adds with the SHA256 used for the files)
289-
Note: check that SHA256SUMS itself doesn't end up in SHA256SUMS, which is a spurious/nonsensical entry.
211+
- Upload to the bitcoincore.org server (`/var/www/bin/bitcoin-core-${VERSION}`):
212+
1. The contents of `./bitcoin/guix-build-${VERSION}/output`, except for
213+
`*-debug*` files.
290214

291-
- Upload zips and installers, as well as `SHA256SUMS.asc` from last step, to the bitcoincore.org server
292-
into `/var/www/bin/bitcoin-core-${VERSION}`
215+
The `*-debug*` files generated by the guix build contain debug symbols
216+
for troubleshooting by developers. It is assumed that anyone that is
217+
interested in debugging can run guix to generate the files for
218+
themselves. To avoid end-user confusion about which file to pick, as well
219+
as save storage space *do not upload these to the bitcoincore.org server,
220+
nor put them in the torrent*.
293221

294-
- A `.torrent` will appear in the directory after a few minutes. Optionally help seed this torrent. To get the `magnet:` URI use:
295-
```bash
296-
transmission-show -m <torrent file>
297-
```
298-
Insert the magnet URI into the announcement sent to mailing lists. This permits
299-
people without access to `bitcoincore.org` to download the binary distribution.
300-
Also put it into the `optional_magnetlink:` slot in the YAML file for
301-
bitcoincore.org.
222+
2. The combined clear-signed message you just created `SHA256SUMS.asc`
223+
224+
- A `.torrent` will appear in the directory after a few minutes. Optionally help
225+
seed this torrent. To get the `magnet:` URI use:
226+
227+
```sh
228+
transmission-show -m <torrent file>
229+
```
230+
231+
Insert the magnet URI into the announcement sent to mailing lists. This permits
232+
people without access to `bitcoincore.org` to download the binary distribution.
233+
Also put it into the `optional_magnetlink:` slot in the YAML file for
234+
bitcoincore.org.
302235

303236
- Update other repositories and websites for new version
304237

@@ -336,14 +269,14 @@ bitcoincore.org.
336269
- https://code.launchpad.net/~bitcoin-core/bitcoin-core-snap/+git/packaging/+ref/0.xx (Click "Create snap package")
337270
- Name it "bitcoin-core-snap-0.xx"
338271
- Leave owner and series as-is
339-
- Select architectures that are compiled via gitian
272+
- Select architectures that are compiled via guix
340273
- Leave "automatically build when branch changes" unticked
341274
- Tick "automatically upload to store"
342275
- Put "bitcoin-core" in the registered store package name field
343276
- Tick the "edge" box
344277
- Put "0.xx" in the track field
345278
- Click "create snap package"
346-
- Click "Request builds" for every new release on this branch (after updating the snapcraft.yml in the branch to reflect the latest gitian results)
279+
- Click "Request builds" for every new release on this branch (after updating the snapcraft.yml in the branch to reflect the latest guix results)
347280
- Promote release on https://snapcraft.io/bitcoin-core/releases if it passes sanity checks
348281

349282
- This repo

0 commit comments

Comments
 (0)