Add release-process.md #964

pull jonasnick wants to merge 4 commits into bitcoin-core:master from jonasnick:release-process changing 4 files +50 −2
  1. jonasnick commented at 7:26 pm on July 7, 2021: contributor

    This is an attempt at a simple release process. Fixes #856. To keep it simple, there is no concept of release candidates for now.

    The release version is determined by semantic versioning of the API. Since it does not seem to be a lot of work, it is proper to also version the ABI with the libtool versioning system. This versioning scheme (semver API, libtool versioning ABI) follows the suggestion in the autotools mythbusters.

    Experimental modules are a bit of a headache, as expected. This release process suggests to treat any change in experimental modules as backwards compatible. That way, users of stable modules are not bothered by frequent non-backwards compatible releases. But a downside is that one must not use experimental modules in shared libraries (which should be mentioned in the README?). It would be nice if we could make the schnorrsig module stable in the not too distant future (see also #817).

  2. rustyrussell commented at 0:52 am on July 30, 2021: contributor
    This looks good! Note that c-lightning has a tool which extracts Changelog entries from commit messages, and also a bot that tests they exist for each PR (or Changelog-None is in GitHub description of PR).
  3. prusnak commented at 9:03 am on July 30, 2021: none
    I suggest to use the format described here: https://keepachangelog.com/ - the guide also mentions that ChangeLog is not a git log dump :-)
  4. rustyrussell commented at 11:29 am on July 30, 2021: contributor

    I suggest to use the format described here: https://keepachangelog.com/ - the guide also mentions that ChangeLog is not a git log dump :-)

    Just to be clear: our tool extracts lives starting with Changelog-(Added|Fixed|Changed|Deprecated|Removed) and adds links to the PRs and sorts them :)

  5. prusnak commented at 12:04 pm on July 30, 2021: none

    our tool extracts lives

    God, what kind of tools do you use?! 😁

  6. jonasnick commented at 7:51 pm on July 30, 2021: contributor
    Thanks for the feedback. I added an Unreleased section to the changelog and categories as suggested by keepachangelog.com. I think in most cases the titles of PRs are sufficiently descriptive such that CHANGELOG entries can be title of PR + link. EDIT: And if a PR fixes, adds or changes multiple distinct things then ideally they would be listed separately in the CHANGELOG.
  7. jonasnick force-pushed on Sep 3, 2021
  8. jonasnick cross-referenced this on Sep 3, 2021 from issue Add release-process.md by jonasnick
  9. real-or-random assigned real-or-random on Oct 14, 2021
  10. real-or-random unassigned real-or-random on Oct 14, 2021
  11. real-or-random requested review from real-or-random on Oct 14, 2021
  12. in configure.ac:11 in c9ad320f1d outdated 
     7+define(_PKG_VERSION_MAJOR, 0)
 8+define(_PKG_VERSION_MINOR, 1)
 9+define(_PKG_VERSION_BUILD, 0)
10+define(_PKG_VERSION_IS_RELEASE, false)
11+
12+AC_INIT([libsecp256k1],m4_join([.], _PKG_VERSION_MAJOR, _PKG_VERSION_MINOR, _PKG_VERSION_BUILD)m4_if(_PKG_VERSION_IS_RELEASE, [true], [], [-pre]),[https://github.com/bitcoin-core/secp256k1/issues],[secp256k1],[https://github.com/bitcoin-core/secp256k1])
    real-or-random commented at 12:38 pm on October 15, 2021:
    nit: I think the full project name should also be “libsecp256k1” (with the lib)
    jonasnick commented at 4:26 pm on October 15, 2021:
    good point, fixed
  13. real-or-random commented at 1:31 pm on October 15, 2021: contributor
    ACK mod nit
  14. jonasnick force-pushed on Oct 15, 2021
  15. real-or-random approved
  17. elichai commented at 10:17 am on October 17, 2021: contributor
    ACK 56c5bff
  18. Rogelio165 approved
  19. sipa commented at 10:48 pm on December 3, 2021: contributor
    ACK procedure/changes, but somehow CI does not like this.
  20. jonasnick force-pushed on Dec 4, 2021
  21. jonasnick commented at 11:05 am on December 4, 2021: contributor
    rebased
  22. real-or-random approved
  23. real-or-random commented at 10:20 am on December 5, 2021: contributor
    utACK 86d0b9eba0b191319c8b6dbfd9d014420f06c836
  24. sipa commented at 3:20 pm on December 5, 2021: contributor
    Hmm, what is the expected difference between the package version and the library version? Why would they not be the same?
  25. real-or-random commented at 4:51 pm on December 5, 2021: contributor
    @sipa See https://autotools.io/libtool/version.html @jonasnick Sorry, needs trivial rebase again.
  26. sipa commented at 5:02 pm on December 5, 2021: contributor
    Can we write in the release process document how each of the 6 numbers are supposed to be updated as a function of the changes in such releases?
  27. sipa commented at 5:14 pm on December 5, 2021: contributor

    Another question (not necessarily something to be explicitly explained in the release process here, but still something that isn’t currently clear to me): what branches structure are the release branches going to use? Possibilities:

    • All release branches branch off master, and thus there is no (clean) way to create a x.y.(z+1) after x.(y+1).z has been released.
    • The branch for x.(y+1).0 branches off the x.y.0 branch; the branch for x.y.(z+1) branches off the x.y.z one. Open questions with this:
      • How to obtain monotonically increasing library “revision” value in the presence of branches?
      • When creating a new branch by forking an already-released branch, would that imply resetting the IS_RELEASE variable? Or do we create the fork at the last commit before the one that sets the IS_RELEASE variable?
  28. jonasnick commented at 3:27 pm on December 6, 2021: contributor

    @sipa The rules are described in configure.ac (“The library version is based on libtool versioning of the ABI. The set of rules for updating the version can be found here: https://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html") or do you mean copying over the rules to the release-process.md? I thought it’s best to have the rules where they version is set because it serves both as a doc of the existing values as well as how to update.

    Another question

    That’s a good question. I’d like it answered in the release_process.md. How does Bitcoin Core do this? I would have thought everything is based off master except patches to earlier versions are done by branching off the earlier release branch. I think this would only have to be done for patches because it’s unlikely we release a x.(y+1).z when (x+1).y.z is already released. Btw, “revision” isn’t monotonically increasing, it’s set to if there’s any change to the interface (including additions).

  29. jonasnick force-pushed on Dec 6, 2021
  30. sipa commented at 7:38 pm on December 6, 2021: contributor

    @jonasnick Yes, I meant including the actual rules for incrementing the library version somewhere, not just a reference. I find the rules described in that link kind of vague, and I also had never heard about the concept of library versions at all; if someone is in a similar situation, and just sees the link they may not realize it’s actually explaining why it’s different from the numbers above.

    That’s a good question. I’d like it answered in the release_process.md. How does Bitcoin Core do this? I would have thought everything is based off master except patches to earlier versions are done by branching off the earlier release branch. I think this would only have to be done for patches because it’s unlikely we release a x.(y+1).z when (x+1).y.z is already released. Btw, “revision” isn’t monotonically increasing, it’s set to if there’s any change to the interface (including additions).

    Bitcoin Core’s release process is roughly:

    • As a general rule, with very few exceptions, all PRs are made to the master branch.
    • Every so often the master branch is forked off to create a major release branch (e.g. the 22.x branch). After that point, future changes in master may be backported to the 22.x branch if they’re bugfixes or somehow specifically relevant for that release. At some point, release candidates v22.0rc1, v22.0rc2, … are created from this branch, and finally the final v22.0 tag is created.
    • Minor releases (e.g. v22.1) are created by continuing to backport changes (bugfixes, mostly) from the master branch into the 22.x branch after v22.0 is released, en then later in the same branch tagging v22.1rc1, v22.1rc2, …, and v22.1. These can be made for multiple major release branches simultnaneously (e.g. a bugfix in master is sufficiently important that it deserves going into major releases 21 and 20 too, could be backported to all these branches, and then trigger release candidates/releases of new minor releases in all of them.

    So the major difference with what you’re proposing is that Bitcoin Core only has branches for major releases, not for very release, and that branch is then used for potentially multiple tags.

    Btw, “revision” isn’t monotonically increasing, it’s set to if there’s any change to the interface (including additions).

    It’s set to what if there is any change to the interface?

  31. sipa commented at 7:49 pm on December 6, 2021: contributor
    @jonasnick Oh, I noticed that the link in the source is different from the one @real-or-random linked to. That one gives much more concrete instructions already.
  32. jonasnick commented at 8:14 pm on December 6, 2021: contributor

    I don’t see signficant down or upsides with either branching approach so I’d follow Bitcoin Core’s process where applicable because that was the initial intention anyway.

    It’s set to what if there is any change to the interface?

    Lol, sorry, I have a new (terrible) keyboard. 0.

  33. sipa commented at 8:16 pm on December 6, 2021: contributor
    Well, I think there are probably some differences that could justify deviating. For one, I don’t think we expect many “major” releases (in the semver sense) after 1.0, certainly not two per year.
  34. jonasnick commented at 8:23 pm on December 6, 2021: contributor
    Yes, I would have translated Core major -> secp minor and Core minor -> patch. So we’d make one branch per minor release and tag patch versions.
  35. in doc/release-process.md:7 in 4ec57b074b outdated 
    0@@ -0,0 +1,14 @@
1+# Release Process
2+
3+1. Open PR to master that
4+   1. adds release notes to `doc/CHANGELOG.md` and
5+   2. if this is **not** a patch release, updates `_PKG_VERSION_{MAJOR,MINOR}` and `_LIB_VERSIONS_*` in `configure.ac`
6+2. After the PR is merged,
7+   * if this is **not** a patch release, create a release branch with name `MAJOR.MINOR.x`.
    real-or-random commented at 8:39 am on December 7, 2021:
    nit: So I assume x is a literal x here, right, so this is 1.2.x. Then we could just call it 1.2. I think this is in fact closer to Core (just MAJOR.MINOR), and this is how you usually abbreviate versions: Just drop the parts you don’t care about.
    jonasnick commented at 8:44 pm on December 7, 2021:
    Core creates a MAJOR.x branch (where x is a literal x) according to @sipa’s description (core branches).
    sipa commented at 4:03 pm on December 8, 2021:
    I’m fine with either. I think Bitcoin Core went with “22.x” because branches that are just a number are a bit weird, but in the end it’s all just arbitrary conventions.
    jonasnick commented at 5:03 pm on December 8, 2021:
    Ok, I removed the .x because it looks nicer.
  36. real-or-random approved
  37. real-or-random commented at 8:40 am on December 7, 2021: contributor
    I agree with all the additions, this looks good.
  38. in doc/release-process.md:4 in 4ec57b074b outdated 
    0@@ -0,0 +1,14 @@
1+# Release Process
2+
3+1. Open PR to master that
4+   1. adds release notes to `doc/CHANGELOG.md` and
    t-bast commented at 9:57 am on December 7, 2021:

    In several projects, I’ve found it quite painful to write all the release notes at once when we actually do a release (the burden of writing the release notes falls on the guy who publishes the release and needs to document other people’s additions to the codebase).

    Something that worked much better for me was to incrementally update the future release notes: each PR to master that will impact the next release should update the future release notes. This way when we want to publish a release, we only need to do a bit of clean-up, but the release notes are already written and up-to-date. It needs a bit of effort at first to remind contributors to do it, but in the end we usually end up with better release notes.

    Feel free to ignore if you think that doesn’t make sense for this project, but I felt it was worth sharing in case it can be helpful.

    real-or-random commented at 10:10 am on December 7, 2021:
    I think in principle I agree but I’m not really sure. My experience in this repo is that it happens quite often that you ask a contributor to fix a nit before you ACK and then the PR is stalled for months. ;)
    jonasnick commented at 8:39 pm on December 7, 2021:

    Agree on @real-or-random’s point but we can still remind regular contributors to do this. I wouldn’t want to force this on irregular contributors because it’s additional work that discourages from contributing PRs in the first place. We could add a pull request template that optionally requests a changelog update.

    One significant downside of this is that pull requests would all edit similar space in the same file which, when one PR is merged, would require rebasing every other PR.

    real-or-random commented at 10:36 pm on December 7, 2021:

    One significant downside of this is that pull requests would all edit similar space in the same file which, when one PR is merged, would require rebasing every other PR.

    Apparently that’s a real problem which led to a “crisis” in the GitLab project and needs an entirely non-trivial solution: https://about.gitlab.com/blog/2018/07/03/solving-gitlabs-changelog-conflict-crisis/

    I think then the maintainers should create the changelog… I suppose it will be easier for everyone (including maintainers).

    sipa commented at 10:48 pm on December 7, 2021:
    Bitcoin Core uses doc/release-notes-<PRNUMBER>.md files which are added by individual PRs, and are then merged into a release release-notes.md by maintainers (not suggesting we do that to; I think the rate of changes here is low enough that maintainers can just keep track of it).
    real-or-random commented at 12:31 pm on December 10, 2021:

    Just for reference, here’s some docs on the process: https://github.com/bitcoin/bitcoin/blob/23ae7931be50376fa6bda692c641a3d2538556ee/doc/release-process.md#write-the-release-notes https://github.com/bitcoin/bitcoin/blob/23ae7931be50376fa6bda692c641a3d2538556ee/doc/release-notes.md

    This has some helpful notes, e.g., a script to generate a (draft) changelog from git history. This may be helpful to us.

  39. sipa commented at 4:25 pm on December 8, 2021: contributor
    LGTM, feel free to squash.
  40. jonasnick force-pushed on Dec 8, 2021
  41. real-or-random approved
  42. real-or-random commented at 12:32 pm on December 10, 2021: contributor
    ACK c8fd83fb834321fcadd062709624f6fb9a95a40d
  43. build: change libsecp version from 0.1 to 0.1.0-pre b4b02fd8c4
  44. jonasnick force-pushed on Dec 23, 2021
  45. jonasnick commented at 2:46 pm on December 23, 2021: contributor
    rebased
  46. build: set library version to 0.0.0 explicitly 0bd3e4243c
  47. doc: add release_process.md 6f42dc16c8
  48. doc: add CHANGELOG template 3ed0d02bf7
  49. apoelstra commented at 3:56 pm on December 23, 2021: contributor

    utACK 3ed0d02bf7690c68ba3ba74da765614809352049

    Looks great!

  50. real-or-random approved
  51. real-or-random commented at 5:55 pm on December 23, 2021: contributor
    ACK 3ed0d02bf7690c68ba3ba74da765614809352049
  52. elichai commented at 6:15 pm on December 23, 2021: contributor
    ACK b4b02fd8c4276779f115af5985508f54ef9e51be
  53. real-or-random commented at 6:36 pm on December 23, 2021: contributor
    @elichai wrong commit :P
  54. elichai commented at 6:38 pm on December 23, 2021: contributor

    @real-or-random Ops, somehow I keep getting confused on the order of commits in github (in git the latest is on top, in github it’s at the bottom)

    ACK 3ed0d02bf7690c68ba3ba74da765614809352049

  55. jonasnick cross-referenced this on Dec 23, 2021 from issue Prepare initial release by jonasnick
  56. apoelstra commented at 2:20 pm on December 24, 2021: contributor

    @elichai if you have

    0[remote "origin"]
1        fetch = +refs/pull/*:refs/remotes/pr/*

    in your gitconfig, you can do something like git rev-parse pr/964/head | xsel to get the top commit ID.

    You may still type the wrong PR number or write “ACK” in the wrong browser tab, but at least there’s one less mistake you can make :)

  57. sipa commented at 11:17 pm on December 24, 2021: contributor
    ACK 3ed0d02bf7690c68ba3ba74da765614809352049
  58. real-or-random merged this on Dec 25, 2021
  59. real-or-random closed this on Dec 25, 2021
  60. jonasnick cross-referenced this on Jan 2, 2022 from issue Sync Upstream by jonasnick
  61. real-or-random referenced this in commit 21e2d65b79 on Jan 5, 2022
  62. dhruv referenced this in commit 6f7e395acc on Jan 26, 2022
  63. hebasto referenced this in commit 065b6dbf9d on Jan 30, 2022
  64. dhruv referenced this in commit 139d4b881e on Feb 1, 2022
  65. fanquake referenced this in commit 8f8631d826 on Mar 17, 2022
  66. fanquake referenced this in commit 4bb1d7e62a on Mar 17, 2022
  67. fanquake referenced this in commit 465d05253a on Mar 30, 2022
  68. stratospher referenced this in commit 4d5afc9767 on Apr 3, 2022
  69. stratospher referenced this in commit 5b18493cfa on Apr 3, 2022
  70. fanquake referenced this in commit afb7a6fe06 on Apr 6, 2022
  71. gwillen referenced this in commit 35d6112a72 on May 25, 2022
  72. patricklodder referenced this in commit 21badcf9d2 on Jul 25, 2022
  73. patricklodder referenced this in commit 03002a9013 on Jul 28, 2022
  74. janus referenced this in commit 3a0652a777 on Aug 4, 2022
  75. real-or-random cross-referenced this on Aug 24, 2022 from issue release: Checking binary compatibility by real-or-random
  76. sipa referenced this in commit 21ffe4b22a on Dec 12, 2022
  77. str4d referenced this in commit 522190d5c3 on Apr 21, 2023
  78. vmta referenced this in commit e1120c94a1 on Jun 4, 2023
  79. vmta referenced this in commit 8f03457eed on Jul 1, 2023


jonasnick rustyrussell prusnak real-or-random elichai Rogelio165 sipa t-bast apoelstra

github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin-core/secp256k1. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2024-10-30 05:15 UTC
This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me