doc: update release-process.md #29645

glozow commented at 11:29 AM on March 13, 2024: member

While doing various release process things for the first time, I noticed some of our docs are outdated and/or confusing.

DrahtBot commented at 11:29 AM on March 13, 2024: contributor

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Code Coverage

For detailed information about the code coverage, see the test coverage report.

Reviews

See the guideline for information on the review process.

Type	Reviewers
ACK	achow101
Concept ACK	pinheadmz, hebasto

If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

Conflicts

No conflicts as of last run.

DrahtBot added the label Docs on Mar 13, 2024

in doc/release-process.md:165 in 74c44d3d08 outdated

 161 | @@ -161,21 +162,25 @@ Then open a Pull Request to the [guix.sigs repository](https://github.com/bitcoi
 162 |  
 163 |  ### macOS codesigner only: Create detached macOS signatures (assuming [signapple](https://github.com/achow101/signapple/) is installed and up to date with master branch)
 164 |  
 165 | +In the `guix-build-${VERSION}/output/x86_64-apple-darwin` directory:

achow101 commented at 11:48 AM on March 13, 2024:

Also arm64-apple-darwin

pinheadmz commented at 6:14 PM on March 13, 2024:

yep 👍

glozow commented at 5:50 PM on March 21, 2024:

added

achow101 commented at 11:50 AM on March 13, 2024: member

In the "Commit the detached codesign payloads" section, could also mention that only one person should rm -rf ./*, or maybe just change that to rm for the set of sigs being added.

Also the commit titling scheme we're using is now something like <version>: win signature for <rc or final> rather than point to ...

achow101 commented at 5:08 PM on March 13, 2024: member

Should also include the command git checkout --orphan <version> for creating the new detached sigs branch for a major release.

pinheadmz commented at 6:14 PM on March 13, 2024: member

concept ACK

I was also confused by the code signing step.

glozow force-pushed on Mar 21, 2024

glozow commented at 5:52 PM on March 21, 2024: member

In the "Commit the detached codesign payloads" section, could also mention that only one person should rm -rf ./*, or maybe just change that to rm for the set of sigs being added.

I made 2 separate steps for each signer, since they'll be different people.

Also the commit titling scheme we're using is now something like <version>: win signature for <rc or final> rather than point to ...

Wrote scheme like this

achow101 commented at 7:05 PM on March 22, 2024: member

ACK 635d16a2f9617091ab2a81647ff15b96fb0f733e

DrahtBot requested review from pinheadmz on Mar 22, 2024

hebasto commented at 3:22 PM on March 25, 2024: member

Here's some historical context regarding translation related changes suggested in this PR.

Basically, during a release process, there are two kind of operations namely (1) generating an updated resource file and uploading it to the Transifex website and (2) downloading prepared translations from the Transifex website and merging them into this repository.

The first kind involves running make -C src translate command. The second one uses update-translations.py script from the bitcoin-maintainer-tools repository, which in turn relies on Transifex's command-line tx client.

In the past, release maintainers performed all these steps by themselves. Then the process became more involved, requiring an additional interaction between a release maintainer and a developer who conducts translation-related stages.

During the v26.0 release, @fanquake suggested (offline) to fetch translations from the Transifex website just before branching a version branch off. That would allow to keep translations in the master branch updated with no extra efforts.

This PR goes further and proposes skipping translation fetching for every release candidate.

FWIW, the v27.0 release is following the translation handling process as this PR suggests.

The benefit of a new approach is less burden on a release maintainer.

However, I can see a couple of drawbacks as well:

Translators have a shorter period to work on translations. Effectively, it starts at string freeze and ends at branching off, which usually lasts for a month.
If a translatable string is modified after branching off, it won't be translated in the release binary.

Being a translator allows me to assume that a month is enough even for a single person assuming they work on a single translation. Also we heavy exploit the "Translation Memory" Transifex feature, which effectively is a cache allowing to reuse translations from the previous releases.

The second case might be considered as a very rare event.

Anyway, this change in the release process deserves an announcement for translators on the Transifex website.

cc translation-involved people: @luke-jr @laanwj

glozow commented at 4:25 PM on March 25, 2024: member

Thanks for the context @hebasto. I felt that it was appropriate to move from "before every release candidate" to ~"before every major or minor release"~(EDIT: correction, "before branch-off") because

I didn't observe that translations were being updated per release candidate.
It made more sense to me that it'd be per release instead of per release candidate since, as you say, changes in between rcs should be very rare and we would largely have control over this.
As you mentioned, translations were added before branch off this time.

Translators have a shorter period to work on translations. Effectively, it starts at string freeze and ends at branching off, which usually lasts for a month.

In practice, is there a large time difference between branch off and the first release candidate?

I made this change because it seemed like more accurate documentation, definitely not as an attempt to make a controversial alteration the release process. I don't feel strongly and am happy to remove that change.

hebasto commented at 4:48 PM on March 25, 2024: member

I made this change because it seemed like more accurate documentation, definitely not as an attempt to make a controversial alteration the release process. I don't feel strongly and am happy to remove that change.

To clarify my previous comment, I do lean to ACK the suggested changes.

glozow commented at 9:48 AM on April 3, 2024: member

(Yay v26.1) I have a couple more things for the last section, and then will take out of draft.

glozow force-pushed on Apr 4, 2024

glozow marked this as ready for review on Apr 4, 2024

DrahtBot added the label CI failed on Apr 4, 2024

DrahtBot removed the label CI failed on Apr 4, 2024

glozow requested review from achow101 on Apr 15, 2024

glozow assigned fanquake on Apr 15, 2024

glozow unassigned fanquake on Apr 15, 2024

glozow requested review from fanquake on Apr 15, 2024

in doc/release-process.md:239 in 44c421b02a outdated

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

achow101 commented at 3:44 PM on April 15, 2024:

I think we've decided to start uploading all build artifacts, including the debug files, so this sentence and section below can be removed.

glozow commented at 9:43 AM on April 18, 2024:

Removed

in doc/release-process.md:263 in 44c421b02a outdated

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

achow101 commented at 3:48 PM on April 15, 2024:

If we're going to mention torrent generation, maybe also mention the OpenTimestamps file too? Both are generated automatically on the server now.

glozow commented at 9:43 AM on April 18, 2024:

Ah, I didn't even realize they were generated on the server. Edited.

glozow force-pushed on Apr 18, 2024

achow101 commented at 2:00 PM on April 18, 2024: member

I think the "Update repositories and websites for new version" section could be split into 2 distinct steps of update the website, then update the packaging repos. Apparently flathub polls the website for new releases and their bot will automatically open a pr to the flathub repo with the new version hashes. So that step must be done after the website is updated.

[doc] update release-process.md and backports section of CONTRIBUTING

- 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.
- Put bitcoincore.org website updates as a separate step, since
  updating packaging repos may have a dependency on it.
- Update "bitcoin-dev mailing list" to "bitcoin-dev group"
- Document that maintainers should create PRs to collect backports
- Remove section about not uploading `*-debug` files, reader should
  upload all build artifacts.
- Torrent is created automatically, so delete instructions.
- Mention that server also generates ots file automatically.

1ea8674316

glozow force-pushed on Apr 18, 2024

glozow commented at 4:09 PM on April 18, 2024: member

I think the "Update repositories and websites for new version" section could be split into 2 distinct steps

Done, I split into website updates and everything else

achow101 commented at 4:26 PM on April 18, 2024: member

ACK 1ea8674316f2dce0005f6094b6ee111b045dd770

DrahtBot requested review from hebasto on Apr 18, 2024

DrahtBot requested review from pinheadmz on Apr 19, 2024

hebasto commented at 1:59 PM on April 29, 2024: member

Thanks for the context @hebasto. I felt that it was appropriate to move from "before every release candidate" to ~"before every major or minor release"~(EDIT: correction, "before branch-off") because

I didn't observe that translations were being updated per release candidate.

It happens, but very seldom. We can really ignore them as it simplifies the release process significantly.

It made more sense to me that it'd be per release instead of per release candidate since, as you say, changes in between rcs should be very rare and we would largely have control over this.

As you mentioned, translations were added before branch off this time.

However, I think we have to update translations for minor releases.

cc @laanwj

Translators have a shorter period to work on translations. Effectively, it starts at string freeze and ends at branching off, which usually lasts for a month.

In practice, is there a large time difference between branch off and the first release candidate?

Not at all :)

achow101 merged this on May 1, 2024

achow101 closed this on May 1, 2024

achow101 commented at 12:18 AM on May 1, 2024: member

Went ahead with merging this since the vast majority of the changes here are correct and useful. It seems like there are still some questions related to the translations, but I think we can document those later when it becomes apparent that what we're actually doing diverges from the doc.

glozow deleted the branch on Dec 20, 2024

bitcoin locked this on Dec 20, 2025