Prepare initial release

[jonasnick]

Based on #964

[bgermann]

Any chance to make this happen?

[hebasto]

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.

[real-or-random]

I would need to check but have you read the discussion in https://github.com/bitcoin-core/secp256k1/pull/964#issuecomment-986248723 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]

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]

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]

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).

[real-or-random]

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.

[hebasto]

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.

[hebasto]

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]

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

[jonasnick]

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.

[jonasnick]

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]

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.

[jonasnick]

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]

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.

[jonasnick]

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).

[jonasnick]

@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.

[hebasto]

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

?

[jonasnick]

@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.