jonasnick commented at 10:15 pm on December 23, 2021: contributor

Based on #964

jonasnick renamed this:
~~Initial release~~
Prepare initial release
on Dec 23, 2021

jonasnick force-pushed on Dec 27, 2021

real-or-random cross-referenced this on Jan 15, 2022 from issue Modulo-reduce msg32 inside RFC6979 nonce fn to match spec. Fixes #1063 by paulmillr

bgermann commented at 10:26 am on June 4, 2022: none

Any chance to make this happen?

hebasto commented at 8:01 am on July 5, 2022: member

I’ve tested 64e96eecb9127f420875a4345ba66335a4607014 with cross compiling for --host=x86_64-w64-mingw32.

The name of dll has been changed bin/libsecp256k1-0.dll –> bin/libsecp256k1-1.dll, reflecting the change in the _LIB_VERSION_CURRENT value.

jonasnick added this to the milestone initial release (0.x) on Jul 31, 2022

in doc/release-process.md:5 in 64e96eecb9 outdated

0@@ -1,14 +1,17 @@
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+   * adds release notes to `doc/CHANGELOG.md` (set the date of the new release to `YYYY-MM-DD`), and
7+   * if this is **not** a patch release, updates `_PKG_VERSION_{MAJOR,MINOR}` and `_LIB_VERSIONS_*` in `configure.ac`.

hebasto commented at 3:17 pm on August 21, 2022:

0   * if this is **not** a patch release, updates `_PKG_VERSION_{MAJOR,MINOR}` and `_LIB_VERSION_*` in `configure.ac`.

in doc/release-process.md:14 in 64e96eecb9 outdated

17+     Create commit on the release branch that sets `_PKG_VERSION_IS_RELEASE` in `configure.ac` to `true` and replaces the dummy date in `doc/CHANGELOG.md` with the current date.
18+   * if this **is** a patch release open a pull request that
19+     * includes the bugfixes to the `MAJOR.MINOR` branch,
20+     * includes the release note commit from master,
21+     * replaces the dummy date in `doc/CHANGELOG.md` with the current date,
22+     * bumps of `_PKG_VERSION_BUILD` and `_LIB_VERSIONS_*` in `configure.ac`.

hebasto commented at 3:18 pm on August 21, 2022:

0     * bumps of `_PKG_VERSION_BUILD` and `_LIB_VERSION_*` in `configure.ac`.

jonasnick force-pushed on Aug 21, 2022

hebasto commented at 8:49 am on August 24, 2022: member

Tested e0ecf6deb3077edb9be803ac8ebb444b41d94be4 on macOS:

the master branch:

0% otool -L .libs/libsecp256k1.0.dylib 
1.libs/libsecp256k1.0.dylib:
2	/usr/local/lib/libsecp256k1.0.dylib (compatibility version 1.0.0, current version 1.0.0)
3	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1311.100.3)

this PR:

0% otool -L .libs/libsecp256k1.1.dylib
1.libs/libsecp256k1.1.dylib:
2	/usr/local/lib/libsecp256k1.1.dylib (compatibility version 2.0.0, current version 2.0.0)
3	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1311.100.3)

Effectively, in/usr/local/lib/libsecp256k1.<V>.dylib (compatibility version <X>.0.0, current version <X>.<Y>.0):

V = current - age
X = current + 1
Y = revision

Is that what we want?

real-or-random commented at 10:36 am on August 24, 2022: contributor

I would need to check but have you read the discussion in #964 (comment) and the corresponding links?

https://autotools.info/libtool/version.html https://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html

The rules seem to be somewhat obscure at first glance of. But what you get there seems to correspond to what’s described in the autotools mythbuster “Warning” paragraph for Linux.

real-or-random commented at 10:42 am on August 24, 2022: contributor

This may be interesting if we want to provide both libtool and cmake builds in the future: https://github.com/mesonbuild/meson/issues/1451#issuecomment-284845913

hebasto commented at 10:56 am on August 24, 2022: member

I would need to check but have you read the discussion in #964 (comment) and the corresponding links?

https://autotools.info/libtool/version.html https://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html

The rules seem to be somewhat obscure at first glance of. But what you get there seems to correspond to what’s described in the autotools mythbuster “Warning” paragraph for Linux.

Of course, I have.

~My concerns are about V = current - age, which will not increase evenly, will it?~

UPDATE:

Do you mean:

the first is calculated by subtracting age from current.

?

real-or-random commented at 11:03 am on August 24, 2022: contributor

My concerns are about V = current - age, which will not increase evenly, will it?

You mean monotonically? If we follow the algorithm in https://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html, then it’s easy to see that current - age will increase monotonically (if I’m not mistaken).

hebasto approved

hebasto commented at 11:09 am on August 24, 2022: member

ACK e0ecf6deb3077edb9be803ac8ebb444b41d94be4

real-or-random commented at 3:55 pm on August 24, 2022: contributor

You mean monotonically? If we follow the algorithm in gnu.org/software/libtool/manual/html_node/Updating-version-info.html, then it’s easy to see that current - age will increase monotonically (if I’m not mistaken).

Though I agree it can be strange due to setting age = 0 in the last step. That means if we have a backwards-incompatible change (e.g., interface removed), we could have a hop from

2:5:2 -> 0.2.5 to
3:0:0 -> 3.0.0.

So you skip over 1.x and 2.x entirely… I guess that’s fine, just not “elegant”. I’m pretty sure in that case one could also reset current to 1, so one would have 1:0:0 -> 1.0.0. For example, the rules in https://autotools.info/libtool/version.html are a little different and never set age to 0…. (It’s all a huge mess… :shrug: )

This uses the translation for Linux (without the “+1” for Mac OS). See the libtool source for the ugly details.

I’m somewhat concerned that the first release commits us to this strange libtool convention with current, revision, age (which apparently is only used in libtool and no other build system). But on the other hand, I don’t think there’s a way to avoid this unless (we want to get rid of libtool as our main build system). I guess we need to apply tricks, e.g., in CMake to match libtool behavior, but AFAIU, you did this already in the CMake PR (I also found this https://cmake.org/cmake/help/latest/prop_tgt/MACHO_COMPATIBILITY_VERSION.html by the way). I guess we’d need to test it on multiple platforms.

real-or-random cross-referenced this on Aug 24, 2022 from issue release: Checking binary compatibility by real-or-random

hebasto commented at 12:59 pm on August 25, 2022: member

For example, the rules in https://autotools.info/libtool/version.html are a little different and never set age to 0…. (It’s all a huge mess… :shrug: )

Looks like they are wrong.The age must be reset to 0 when backward-incompatible interface changes being introduced. Otherwise, it would mean that the library supports more than one interface, which is wrong.

real-or-random cross-referenced this on Aug 25, 2022 from issue Add vcpkg installation instructions by JonLiu1993

hebasto commented at 4:33 pm on August 25, 2022: member

FWIW, I’ve gathered details about potential future version changes, and their representations for different platforms using the current versioning implementation.

Shared library ABI versioning across platforms

Note that the first 4 columns are identical for each platform-specific table.

Linux – `libsecp256k1.so.<V>`

ABI change	Libtool diff	Libtool C:R:A	V=C-A	SONAME	SONAME.A.R
Inception		0:0:0	0	libsecp256k1.so.0	libsecp256k1.so.0.0.0
Initial release (this PR)		1:0:0	1	libsecp256k1.so.1	libsecp256k1.so.1.0.0
No change	++R	1:1:0	1	libsecp256k1.so.1	libsecp256k1.so.1.0.1
No change	++R	1:2:0	1	libsecp256k1.so.1	libsecp256k1.so.1.0.2
BC *	++C,R=0,++A	2:0:1	1	libsecp256k1.so.1	libsecp256k1.so.1.1.0
No change	++R	2:1:1	1	libsecp256k1.so.1	libsecp256k1.so.1.1.1
BC	++C,R=0,++A	3:0:2	1	libsecp256k1.so.1	libsecp256k1.so.1.2.0
BI **	++C,R=0,A=0	4:0:0	4	libsecp256k1.so.4	libsecp256k1.so.4.0.0

macOS – `libsecp256k1.<V>.dylib`

ABI change	Libtool diff	Libtool C:R:A	V=C-A	compatibility_v=C+1.0.0	current_v=C+1.R.0
Inception		0:0:0	0	1.0.0	1.0.0
Initial release (this PR)		1:0:0	1	2.0.0	2.0.0
No change	++R	1:1:0	1	2.0.0	2.1.0
No change	++R	1:2:0	1	2.0.0	2.2.0
BC	++C,R=0,++A	2:0:1	1	3.0.0	3.0.0
No change	++R	2:1:1	1	3.0.0	3.1.0
BC	++C,R=0,++A	3:0:2	1	4.0.0	4.0.0
BI	++C,R=0,A=0	4:0:0	4	5.0.0	5.0.0

Windows – `libsecp256k1-<V>.dll`

ABI change	Libtool diff	Libtool C:R:A	V=C-A
Inception		0:0:0	0
Initial release (this PR)		1:0:0	1
No change	++R	1:1:0	1
No change	++R	1:2:0	1
BC	++C,R=0,++A	2:0:1	1
No change	++R	2:1:1	1
BC	++C,R=0,++A	3:0:2	1
BI	++C,R=0,A=0	4:0:0	4

* BC – backward-compatible

** BI – backward-incompatible

jonasnick commented at 3:10 pm on December 5, 2022: contributor

I should also move doc/CHANGELOG.md to CHANGELOG.md.

jonasnick force-pushed on Dec 6, 2022

jonasnick commented at 9:57 am on December 6, 2022: contributor

I rebased the PR. After it is merged, the next step would be to create a release branch and tag the release. But after rereading the release process, I see two potential shortcomings:

The version on the master branch is MAJOR.MINOR.0-pre. So the patch version is always 0 on master, even if we’ve actually released patches for MAJOR.MINOR. This might indicate at first glance that master somehow contains an older version. To avoid this and mark the unreleased version more clearly, we could use patch version 99 for the master branch.
The release process currently does not describe when to replace the dummy date of the release in master. And doing this would be an extra step/PR. Maybe it’s easier - at least for now - to avoid the dummy date entirely by using the current date as the release date in the PR to master. This may mean that that date needs to be updated multiple times while the release PR is not merged.

Bezzo100-lab approved

in doc/release-process.md:4 in 330575b39a outdated

0@@ -1,14 +1,17 @@
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+   * adds release notes to `doc/CHANGELOG.md` (set the date of the new release to dummy date `YYYY-MM-DD`), and

real-or-random commented at 2:13 pm on December 6, 2022:

nit: new path of CHANGELOG.md (more instances below)

jonasnick commented at 4:15 pm on December 6, 2022:

fixed

doc: move CHANGELOG from doc/ to root directory 90618e9263

jonasnick force-pushed on Dec 6, 2022

jonasnick commented at 4:18 pm on December 6, 2022: contributor

After talking with @real-or-random I addressed above issues by 1) changing the patch version to 99 on master and 2) removing the dummy date, which required setting an actual release date for the initial release. I picked Thursday!

I’ll do a couple of test release with these instructions on my repo and will report back.

jonasnick force-pushed on Dec 7, 2022

jonasnick commented at 10:39 am on December 7, 2022: contributor

Ok, I’ve made a couple of releases in my fork and updated the release process to include more git commands to avoid mistakes like forgetting to pull. I’ve also clarified a few steps to make it easier to follow.

in CHANGELOG.md:17 in ccf44ab0ef outdated

12+
13+This version was never actually released.
14+The number was given by the build system since the introduction of autotools in Jan 2014 (ea0fe5a5bf0c04f9cc955b2966b614f5f378c6f6).
15+Therefore, this version number does not uniquely identify a set of source files.
16+
17+The following notable changes were made right before the initial release 0.2.0:

real-or-random commented at 5:34 pm on December 7, 2022:

Yes, and I think that means we should list them under 0.2.0, no?

jonasnick commented at 9:13 pm on December 7, 2022:

Those changes all happened while 0.2.0 wasn’t tagged, so in my view they’re part of the “pre-release” 0.1.0. However, this is all somewhat arbitrary. So I changed the date of 0.1.0 to 2013-03-05 to 2021-12-25 which is the date when the initial release process PR was merged and we started keeping track of changes. Consequently, I moved the changes to 0.2.0.

jonasnick force-pushed on Dec 7, 2022

build: change package version to 0.1.0-dev

The suffix -dev is slightly clearer.

Also, since the package version follows semantic versioning, rename
VERSION_BUILD to VERSION_PATCH for clarity.

ad39e2dc41

jonasnick force-pushed on Dec 7, 2022

jonasnick commented at 10:27 pm on December 7, 2022: contributor

Following a suggestion from @real-or-random I changed the proposed release process again. Instead of always having patch version 99 on master, the patch version in master is now always one higher than the most recent release. Besides being a bit more logical, this makes the process a tiny bit easier. The release process now also covers patch releases for old major or minor releases.

I’ll still need to test this new process.

jonasnick force-pushed on Dec 8, 2022

jonasnick commented at 2:03 pm on December 8, 2022: contributor

Another suggestion from @real-or-random: clearly distinguish between “regular” and “maintenance” releases. This makes “regular” releases a bit simpler. I still need to test this.

in CHANGELOG.md:10 in 09f2436e6c outdated

 8 ## [Unreleased]
 9 
10+## [0.2.0] - 2022-12-08
11+
12 ### Changed
13  - Enable modules schnorrsig, extrakeys and ECDH by default in ./configure

real-or-random commented at 2:23 pm on December 8, 2022:

0 - Enabled modules schnorrsig, extrakeys and ECDH by default in ./configure.

nit: seems that we use past tense everywhere else (and this fits the headings), so we could fix this in this PR.

jonasnick commented at 5:28 pm on December 8, 2022:

Fixed (the example at keepachangelog.com uses both present and past tense)

in CHANGELOG.md:21 in 09f2436e6c outdated

15@@ -16,7 +16,9 @@ Each change falls into one of the following categories: Added, Changed, Deprecat
16 ### Added
17  - Added `secp256k1_selftest`, to be used in conjunction with `secp256k1_context_static`.
18 
19-## [MAJOR.MINOR.PATCH] - YYYY-MM-DD
20+## [0.1.0] - 2013-03-05 to 2021-12-25
21+
22+This version was never actually released.

real-or-random commented at 2:25 pm on December 8, 2022:

0This version was in fact never released.

(actually sounds a little bit like it was released in some sense, just not properly…)

jonasnick commented at 5:28 pm on December 8, 2022:

fixed

in doc/release-process.md:9 in 09f2436e6c outdated

16+
17+We distinguish between two types of releases: *regular* and *maintenance* releases.
18+Regular releases are releases of a new major or minor version as well as patches of the most recent release.
19+Maintenance releases, on the other hand, are required for patches of older releases.
20+
21+Note that adding a release entry to CHANGELOG.md requires a release date. This date should match the dates of the remaining steps in the release process, including the date of the tag and the GitHub release.

real-or-random commented at 2:26 pm on December 8, 2022:

0Note that adding a release entry to [CHANGELOG.md](../CHANGELOG.md) requires a release date. This date should match the dates of the remaining steps in the release process, including the date of the tag and the GitHub release.

jonasnick commented at 5:29 pm on December 8, 2022:

fixed

in doc/release-process.md:22 in 09f2436e6c outdated

29+       * adds release notes to [CHANGELOG.md](../CHANGELOG.md) and
30+       * updates `_PKG_VERSION_*`, `_LIB_VERSION_*`, and sets `_PKG_VERSION_IS_RELEASE` to `true` in `configure.ac`.
31+   2. A commit (with commit message `"release: update master after $MAJOR.$MINOR.$PATCH"`, for example) that sets `_PKG_VERSION_IS_RELEASE` to `false` and `_PKG_VERSION_PATCH` to `$PATCH + 1` and increases `_LIB_VERSION_REVISION`.
32+2. After the PR is merged, tag the commit:
33+   ```
34+   BRANCH_COMMIT=<commit of step 1.1>

real-or-random commented at 2:28 pm on December 8, 2022:

0   BRANCH_COMMIT=<commit of step 1.i>

That’s how it’s rendered.

jonasnick commented at 5:29 pm on December 8, 2022:

fixed

in doc/release-process.md:19 in 09f2436e6c outdated

26+
27+1. Open PR to the master branch that includes the following commits:
28+   1. A commit (with commit message `"release: prepare for $MAJOR.$MINOR.$PATCH"`, for example) that
29+       * adds release notes to [CHANGELOG.md](../CHANGELOG.md) and
30+       * updates `_PKG_VERSION_*`, `_LIB_VERSION_*`, and sets `_PKG_VERSION_IS_RELEASE` to `true` in `configure.ac`.
31+   2. A commit (with commit message `"release: update master after $MAJOR.$MINOR.$PATCH"`, for example) that sets `_PKG_VERSION_IS_RELEASE` to `false` and `_PKG_VERSION_PATCH` to `$PATCH + 1` and increases `_LIB_VERSION_REVISION`.

real-or-random commented at 2:33 pm on December 8, 2022:

0   2. A commit (with commit message `"release: Bump version after $MAJOR.$MINOR.$PATCH"`, for example) that sets `_PKG_VERSION_IS_RELEASE` to `false` and `_PKG_VERSION_PATCH` to `$PATCH + 1` and increases `_LIB_VERSION_REVISION`.

Mentioning “master” feels somewhat wrong because the commit will end up on other branches, too. I think this is minimally clearer.

(My suggestion includes starting with a capital letter after the colon in the commit messages, because I find this more readable. But this is just my preference, feel free to stick to lower case.)

jonasnick commented at 5:29 pm on December 8, 2022:

true, fixed (and sticked with lowercase for now)

in doc/release-process.md:34 in 09f2436e6c outdated

41+4. Create a new GitHub release with a link to the corresponding entry in [CHANGELOG.md](../CHANGELOG.md).
42+
43+## Maintenance release
44+
45+Note that some releases do not require maintenance, even if they include bugs.
46+This is the case when users of the library are able to update to a newer, compatible release that does not include the bug.

real-or-random commented at 2:44 pm on December 8, 2022:

0This is the case when users of the library are able to update to a newer, backwards-compatible release that does not include the bug.

jonasnick commented at 5:29 pm on December 8, 2022:

Chose sipa’s suggestion below.

in doc/release-process.md:39 in 09f2436e6c outdated

46+This is the case when users of the library are able to update to a newer, compatible release that does not include the bug.
47+
48+1. Open PR to the master branch that includes a commit (with commit message `"release: prepare for $MAJOR.$MINOR.$PATCH"`, for example) that adds release notes to [CHANGELOG.md](../CHANGELOG.md).
49+2. If `$PATCH = 1`, create maintenance branch `$MAJOR.$MINOR`:
50+     ```
51+     BRANCH_COMMIT=<id of commit that set _PKG_VERSION_* to $MAJOR.$MINOR>

real-or-random commented at 2:45 pm on December 8, 2022:

Couldn’t we just use the tag here?

0     BRANCH_COMMIT=v$MAJOR.$MINOR.$PATCH

If yes, then maybe it fits on a single line. Not sure if that’s more readable.

jonasnick commented at 5:30 pm on December 8, 2022:

done (should be v$MAJOR.$MINOR.0)

real-or-random commented at 2:59 pm on December 8, 2022: contributor

That looks really good, the split into two sections is much easier to read.

A high-level thought for maintenance releases: In principle, we could add multiple PRs to a maintenance branch before we do the PR that cuts the release. And this is true even for the first maintenance release. So a more general process: is

Create a branch from the tag, bump PATCH+1 on this branch and set Release = false
(Work on the branch)
Open a PR that creates the release (“prepare” commit + second commit that bumps PATCH+1) again.

But nothing in the current version is wrong, and this is just for maintenance releases. So we can adjust a bit once we make such a release.

jonasnick force-pushed on Dec 8, 2022

jonasnick commented at 4:57 pm on December 8, 2022: contributor

Testing was ok. I released 0.2.0, 0.3.0 and 0.2.1 (maintenance) in my fork which unveiled a minor bug in the process (fixed now).

in doc/release-process.md:33 in 0d92e6d758 outdated

40+   ```
41+4. Create a new GitHub release with a link to the corresponding entry in [CHANGELOG.md](../CHANGELOG.md).
42+
43+## Maintenance release
44+
45+Note that some releases do not require maintenance, even if they include bugs.

sipa commented at 5:21 pm on December 8, 2022:

I’d formulate this in negated form, e.g.:

Note that bugfixes only need to be backported to releases for which no compatible release without the bug exists.

jonasnick commented at 5:30 pm on December 8, 2022:

done

jonasnick force-pushed on Dec 8, 2022

jonasnick commented at 5:31 pm on December 8, 2022: contributor

@real-or-random It’s true that the process doesn’t work if a maintenance release requires multiple PRs. Agree that we can adjust this once we have to do such a release.

in doc/release-process.md:15 in 44579f7845 outdated

22+
23+This process also assumes that there will be no minor releases for old major releases.
24+
25+## Regular release
26+
27+1. Open PR to the master branch that includes the following commits:

sipa commented at 8:00 pm on December 8, 2022:

As specified, it’s necessary that this (1) PR is merged in a linearized fashion (so nothing can be merged into master between the time the PR is created and it being merged), otherwise there may be commits in the PR’s merge base’s ancestry which are missing from the tag. That’s not a disaster, but it’d be pretty confusing.

There are a number of approaches to address this:

Don’t care about it - just make sure the “release-prepare” PR is always merged quickly, without any other merged in between.
Use two separate PRs, and tag the merge-commit of the first.
Use two commits (or at least the first one) that’s not part of a PR, but just immediately pushed by a maintainer to the master branch.

Thoughts?

real-or-random commented at 10:07 pm on December 8, 2022:

Urghs, this is a good point. (And this was not a problem with the previous approach…)

Don’t care about it

Well we anyway need to open the PR for the right date to get the release date right… So yeah, this is doable but it still seems error-prone. (And releases are the one thing where we don’t want to make mistakes, because we cannot correct them without another release.)

Use two separate PRs, and tag the merge-commit of the first.

Ok, that works. I tried to avoid two PRs but ok. What if we have a single PR, merge that locally with the merge tool, tag the merge, let the merging maintainer add the “bump after release” commit manually, and then push the result. That saves the second PR and having that one commit with PR is harmless. (And if there’s a problem with the “bump after release” commit, then we can just fix it on master and it won’t affect the release.)

Use two commits (or at least the first one) that’s not part of a PR, but just immediately pushed by a maintainer to the master branch.

Is that what I just wrote above? I’m not sure. You say at least the first commit should be manual and not part of the PR, and I don’t see how that would work. (In my suggestion, the second commit is done manually.)

sipa commented at 10:41 pm on December 8, 2022:

I don’t see why the second commit matters? It’s past the tag, so it can’t affect it.

All that matters is that there is a stable point on the master branch after the first commit. That can be achieved by it being in a separate PR, and using the merge commit of that PR as the tag, or by just pushing a commit and marking that as the tag.

real-or-random commented at 8:00 am on December 9, 2022:

I don’t see why the second commit matters? It’s past the tag, so it can’t affect it.

All that matters is that there is a stable point on the master branch after the first commit. That can be achieved by it being in a separate PR, and using the merge commit of that PR as the tag, or by just pushing a commit and marking that as the tag.

Yes, we’re in full agreement here!

So I think we should

tag the merge commit of a PR
then get the “release: update master …” commit on master (with or without a PR).

Now that I think about this again, I tend so say let’s make a PR so that we never break the implicit “don’t push without PR” rule (this also means other maintainers will see it etc.) But to make sure the process is not overly complicated and interactive, I suggest that the maintainer preparing the release simply merges this second PR without an ACK. (And indeed, even if we then spot a mistake in the second PR, it won’t affect the release).

jonasnick commented at 9:53 am on December 9, 2022:

That’s quite unfortunate, I did not consider this.

So I think we should

tag the merge commit of a PR

then get the “release: update master …” commit on master (with or without a PR).

One issue with this approach is that IS_RELEASE is set to true in the merge commit as well as in the commit that set it to true. Therefore, we have two (maybe significantly) different states of the repo that are marked as IS_RELEASE. Another problem with this approach is that the repo is locked after the first PR until the second commit lands in the repo (unless you ignore IS_RELEASE and VERSION_PATCH for a while).

Another approach is that we revert the release process back to a version where we set the patch version of master to 99 and branch off from before we set IS_RELEASE which is preserved here. This version, however, has some subtle edge cases that made me prefer the current version of the release process.

I would have no problem with the approach that locks the repo until the PR is merged (“don’t care about it”) if we could reasonably ensure that no mistakes will happen. But I have no better ideas than mentioning it in the release process and in the OP of the PR.

sipa commented at 6:27 pm on December 9, 2022:

Would it be an option to just always create a branch for every MAJOR.MINOR.*, and then only set the IS_RELEASE on a commit in that branch, and never on master?

jonasnick commented at 2:56 pm on December 12, 2022:

As per our discussion elsewhere I changed the release process to @real-or-random’s suggestion above.

hebasto commented at 8:58 am on December 9, 2022: member

nit: I found the change type order here more preferable. Maybe follow it and reorder in our CHANGELOG.md as well like that:

Added
Changed
Deprecated

?

in configure.ac:17 in 44579f7845 outdated

16 # All changes in experimental modules are treated as if they don't affect the
17 # interface and therefore only increase the revision.
18-define(_LIB_VERSION_CURRENT, 0)
19-define(_LIB_VERSION_REVISION, 0)
20+define(_LIB_VERSION_CURRENT, 1)
21+define(_LIB_VERSION_REVISION, 1)

hebasto commented at 9:08 am on December 9, 2022:

Why has revision been incremented? Incrementing of current implies setting revision to zero.

jonasnick commented at 1:56 pm on December 9, 2022:

Did you notice that CURRENT and REVISION are incremented in different commits? The idea is that after we create the release commit we immediately increment the package PATCH version and library REVISION to have sensible version numbers in master that are distinct from the release.

hebasto commented at 2:03 pm on December 9, 2022:

Did you notice that CURRENT and REVISION are incremented in different commits?

I didn’t (

In that case, the changes make sense.

in doc/release-process.md:9 in 44579f7845 outdated

16+
17+We distinguish between two types of releases: *regular* and *maintenance* releases.
18+Regular releases are releases of a new major or minor version as well as patches of the most recent release.
19+Maintenance releases, on the other hand, are required for patches of older releases.
20+
21+Note that adding a release entry to [CHANGELOG.md](../CHANGELOG.md) requires a release date. This date should match the dates of the remaining steps in the release process, including the date of the tag and the GitHub release.

hebasto commented at 9:21 am on December 9, 2022:

Is ti worth mentioning in the CHANGELOG.md for each regular release whether it is ABI backward compatible or not? A clear statement about ABI backward compatibility will also help to modify _LIB_VERSION_* variables properly.

jonasnick commented at 1:56 pm on December 9, 2022:

It would make more sense to me to do the opposite and mention that we make little guarantees about the library version. We don’t have methods to accurately determine ABI compatibility and so we can either put reasonable effort into attempting proper library versioning or not having library versions at all. So far the consensus seemed to be that we do the former.

jonasnick commented at 2:03 pm on December 9, 2022:

OTOH if our resonable-effort approach to library versioning would indicate that it’s not consistent with semantic versioning, then I agree that it makes sense to mention that in the changelog. You think that’s worth adding to the release-process.md?

sipa commented at 6:09 pm on December 9, 2022:

I don’t see why it would be hard to assess ABI compatibility? Sure there is always a chance we miss something, as we don’t have formal methods to determine it, but I don’t think it’s unreasonable to at least try and have a very good chance of getting it right?

jonasnick commented at 7:58 pm on December 9, 2022:

I don’t think it’s unreasonable to at least try and have a very good chance of getting it right

Good, then there doesn’t seem to be disagreement.

If we want to mention ABI compatibility in every release note, we could add a section ### ABI compatibility (or so) to the release notes that (somewhat cautiously) mentions how we set the library version.

jonasnick commented at 2:57 pm on December 12, 2022:

I added a section ### ABI compatibility to the changelog and mention it in the release process.

jonasnick commented at 1:57 pm on December 9, 2022: contributor

@hebasto Sure, we can do that. I don’t have a particular preference about the order except that I wouldn’t agree with the “security-last” approach of keepachangelog.com.

jonasnick force-pushed on Dec 12, 2022

hebasto commented at 4:09 pm on December 12, 2022: member

Formatting nits:

 0--- a/doc/release-process.md
 1+++ b/doc/release-process.md
 2@@ -15,8 +15,8 @@ This process also assumes that there will be no minor releases for old major rel
 3 ## Regular release
 4 
 5 1. Open a PR to the master branch with a commit (using message `"release: prepare for $MAJOR.$MINOR.$PATCH"`, for example) that
 6-       * adds release notes to [CHANGELOG.md](../CHANGELOG.md) (make sure to include an entry for `### ABI Compatibility`) and
 7-       * updates `_PKG_VERSION_*`, `_LIB_VERSION_*`, and sets `_PKG_VERSION_IS_RELEASE` to `true` in `configure.ac`.
 8+    * adds release notes to [CHANGELOG.md](../CHANGELOG.md) (make sure to include an entry for `### ABI Compatibility`) and
 9+    * updates `_PKG_VERSION_*`, `_LIB_VERSION_*`, and sets `_PKG_VERSION_IS_RELEASE` to `true` in `configure.ac`.
10 2. After the PR is merged, tag the commit and push it:
11    ```
12    RELEASE_COMMIT=<merge commit of step 1>
13@@ -24,7 +24,7 @@ This process also assumes that there will be no minor releases for old major rel
14    git push git@github.com:bitcoin-core/secp256k1.git v$MAJOR.$MINOR.$PATCH
15    ```
16 3. Open a PR to the master branch with a commit (using message `"release: bump version after $MAJOR.$MINOR.$PATCH"`, for example) that sets `_PKG_VERSION_IS_RELEASE` to `false` and `_PKG_VERSION_PATCH` to `$PATCH + 1` and increases `_LIB_VERSION_REVISION`.
17-  * If other maintainers are not present to approve the PR, it can be merged without ACKs.
18+    * If other maintainers are not present to approve the PR, it can be merged without ACKs.
19 4. Create a new GitHub release with a link to the corresponding entry in [CHANGELOG.md](../CHANGELOG.md).
20 
21 ## Maintenance release

UPD. For the latter diff, perhaps this variant is more meaningful:

 0--- a/doc/release-process.md
 1+++ b/doc/release-process.md
 2@@ -24,7 +24,9 @@ This process also assumes that there will be no minor releases for old major rel
 3    git push git@github.com:bitcoin-core/secp256k1.git v$MAJOR.$MINOR.$PATCH
 4    ```
 5 3. Open a PR to the master branch with a commit (using message `"release: bump version after $MAJOR.$MINOR.$PATCH"`, for example) that sets `_PKG_VERSION_IS_RELEASE` to `false` and `_PKG_VERSION_PATCH` to `$PATCH + 1` and increases `_LIB_VERSION_REVISION`.
 6-  * If other maintainers are not present to approve the PR, it can be merged without ACKs.
 7+
 8+\* If other maintainers are not present to approve the PR, it can be merged without ACKs.
 9+
10 4. Create a new GitHub release with a link to the corresponding entry in [CHANGELOG.md](../CHANGELOG.md).
11 
12 ## Maintenance release

in doc/release-process.md:18 in 615e7a68fc outdated

25+This process also assumes that there will be no minor releases for old major releases.
26+
27+## Regular release
28+
29+1. Open a PR to the master branch with a commit (using message `"release: prepare for $MAJOR.$MINOR.$PATCH"`, for example) that
30+       * adds release notes to [CHANGELOG.md](../CHANGELOG.md) (make sure to include an entry for `### ABI Compatibility`) and

sipa commented at 7:02 pm on December 12, 2022:

Would it make sense to say finalize release notes, as ideally, the bulk of release notes was added by the respective PRs that introduced observable changes?

jonasnick commented at 7:49 pm on December 12, 2022:

Fixed.

in doc/release-process.md:34 in 615e7a68fc outdated

41+
42+## Maintenance release
43+
44+Note that bugfixes only need to be backported to releases for which no compatible release without the bug exists.
45+
46+1. Open PR to the master branch that includes a commit (with commit message `"release: prepare for $MAJOR.$MINOR.$PATCH"`, for example) that adds release notes to [CHANGELOG.md](../CHANGELOG.md).

sipa commented at 7:02 pm on December 12, 2022:

It may be useful to clean up the release notes in master at this point (or adding them, if the bugfixes themselves didn’t do that), but I find it a bit strange to have this commit refer to the specific version being release, as the master branch at this point is work towards another version.

For example, say v3.1.0 was already released, and a bug is found. The bug was merged in master already. Master at this point is on its way to become v3.2.0 or v4.0.0. A v3.1.1 happens to be necessary to fix the bug however. I’d say the only required step is the creation of a 3.1 branch, branching off the v3.1.0 merge commit, and adding the release notes relevant for v3.1.1 there. Having that Prepare for v3.1.1 strikes me as unnecessary and confusing in master because master has changes that won’t be in v3.1.1, though it may be useful to at the same time clean up the release notes related to the bug in master too, if needed.

real-or-random commented at 7:29 pm on December 12, 2022:

I’d say the only required step is the creation of a 3.1 branch, branching off the v3.1.0 merge commit, and adding the release notes relevant for v3.1.1 there.

Hm yeah, I don’t know. So far I held the belief that it’s a good thing to treat the changelog more like a “global” thing that lists all releases (regular and maintenance across branches). Because it makes sense to keep a list of all releases somehwere. And then the canonical place for it is master. (Or outside the repo, e.g., in a wiki, but that comes with other difficulties.)

How do other projects handle this?

(Happy to postpone this and all other things related to maintenance releases to the future)

sipa commented at 7:37 pm on December 12, 2022:

Hmm, I hadn’t considered getting release notes for bugfix releases in master - I’d have assumed we’d backport those separately after the release is out. But it’s better indeed if it’s part of the release process.

How about moving step (1) to be after step (6), and calling it Add $MAJOR.$MINOR.$PATCH to release notes? Step (1) happens in a different branch than everything else, so the order shouldn’t matter.

jonasnick commented at 7:42 pm on December 12, 2022:

How about moving step (1) to be after step (6), and calling it Add $MAJOR.$MINOR.$PATCH to release notes? Step (1) happens in a different branch than everything else, so the order shouldn’t matter.

sgtm

real-or-random commented at 7:47 pm on December 12, 2022:

i.e. first add 3.1.1 release notes to the 3.1 branch, do the release and then port the 3.1.1 release notes to master? that sounds reasonable.

sipa commented at 7:48 pm on December 12, 2022:

i.e. first add 3.1.1 release notes to the 3.1 branch, do the release and then port the 3.1.1 release notes to master? that sounds reasonable.

Right, exactly.

jonasnick commented at 7:49 pm on December 12, 2022:

done

jonasnick force-pushed on Dec 12, 2022

doc: improve release process

- make version on master always equal to latest release with patch+1
- separate regular from maintenance releases
- add more git commands to prevent accidents
- mention that one needs to somehow deal with release dates
- _LIB_VERSIONS_ -> _LIB_VERSION_
- don't push all tags in step 4
- add required message to git tag
- add suggested commit messages

b1f992a552

changelog: make order of change types match keepachangelog.com 13bf1b6b32

jonasnick force-pushed on Dec 12, 2022

jonasnick commented at 7:53 pm on December 12, 2022: contributor

@hebasto Thanks. I fixed the formatting.

sipa commented at 7:56 pm on December 12, 2022: contributor

ACK c5a94a65826159d4084bc2d4af9f69af995a5fc8

in CHANGELOG.md:13 in c5a94a6582 outdated

 8+
 9+### Added
10+ - Added `secp256k1_selftest`, to be used in conjunction with `secp256k1_context_static`.
11+
12+### Changed
13+ - Enabled modules schnorrsig, extrakeys and ECDH by default in ./configure.

real-or-random commented at 7:58 pm on December 12, 2022:

0 - Enabled modules schnorrsig, extrakeys and ECDH by default in `./configure`.

jonasnick commented at 8:22 pm on December 12, 2022:

Fixed

jonasnick force-pushed on Dec 12, 2022

jonasnick commented at 8:22 pm on December 12, 2022: contributor

Set the release date to 2022-12-12 (today).

real-or-random approved

real-or-random commented at 8:31 pm on December 12, 2022: contributor

ACK 38c9096236cd0c45db2aa258888caf97fbd92b78

sipa commented at 8:32 pm on December 12, 2022: contributor

ACK 38c9096236cd0c45db2aa258888caf97fbd92b78

hebasto approved

hebasto commented at 8:46 pm on December 12, 2022: member

ACK 38c9096236cd0c45db2aa258888caf97fbd92b78, I have reviewed the changes, except for Add/Changed//Deprecated paragraphs in the CHANGELOG.md, and they look OK.

The entire release process differs from one in the Bitcoin Core repo, but it still looks reasonable.

build: add missing files to EXTRA_DIST 6d1784a2e2

release: prepare for initial release 0.2.0

There are plenty of unreleased variants of libsecp256k1 version 0.1.0
(libsecp256k1.so.0.0.0) in the wild. We choose a new version number to allow a
clear distinction.

There are variants of 0.1.0 that are incompatible with the initial release,
hence we increase the minor version to arrive at version number 0.2.0. For the
same reason, we increase the LIB_VERSION_CURRENT and keep AGE at 0.

The changelog for 0.2.0 consists of the relevant changes since 2021-12-25, which
is the date when the initial release process PR was merged (and the library
version was set to a pre-release, see 423b6d19d373f1224fd671a982584d7e7900bc93).
This is somewhat arbitrary but at least points readers to relevant changes.

e025ccdf74

jonasnick force-pushed on Dec 12, 2022

jonasnick commented at 9:27 pm on December 12, 2022: contributor

@real-or-random noticed that the distribution (make dist) is missing some files. I added a commit to fix that.

sipa commented at 9:38 pm on December 12, 2022: contributor

ACK e025ccdf7473702a76bb13d763dc096548ffefba

real-or-random approved

real-or-random commented at 9:53 pm on December 12, 2022: contributor

ACK 90618e9263ebc2a0d73d487d6d94fd3af96b973c

sipa merged this on Dec 12, 2022

sipa closed this on Dec 12, 2022

real-or-random cross-referenced this on Dec 12, 2022 from issue Create a release by shazow

sipa referenced this in commit 9d47e7b71b on Dec 13, 2022

tcharding referenced this in commit ccc5d293db on Dec 16, 2022

tcharding referenced this in commit 9907c88fdb on Dec 16, 2022

tcharding referenced this in commit 7a515d76e9 on Dec 19, 2022

tcharding referenced this in commit 4662d83e45 on Dec 20, 2022

tcharding referenced this in commit 2dad589394 on Dec 20, 2022

apoelstra referenced this in commit 748dcd9401 on Dec 21, 2022

dhruv referenced this in commit 78b5ddf28b on Jan 11, 2023

dhruv referenced this in commit 215394a1d5 on Jan 11, 2023

SomberNight cross-referenced this on Feb 3, 2023 from issue Support latest Debian libsecp256k1 package by romanz

SomberNight referenced this in commit dd141c7fa0 on Feb 3, 2023

div72 referenced this in commit 945b094575 on Mar 14, 2023

str4d referenced this in commit 0df7b459f6 on Apr 21, 2023

vmta referenced this in commit e1120c94a1 on Jun 4, 2023

vmta referenced this in commit 8f03457eed on Jul 1, 2023

jonasnick cross-referenced this on Jul 18, 2023 from issue Upstream PRs 993, 1152, 1165, 1126, 1168, 1173, 1055 by jonasnick

Prepare initial release #1055

Shared library ABI versioning across platforms

Linux – libsecp256k1.so.<V>

macOS – libsecp256k1.<V>.dylib

Windows – libsecp256k1-<V>.dll

Linux – `libsecp256k1.so.<V>`

macOS – `libsecp256k1.<V>.dylib`

Windows – `libsecp256k1-<V>.dll`