[resent without embedded table]

I've completed the BX release, with corresponding branch and tag updates.

I've tried to accommodate everyone's inputs. Instead of providing a long
explanation, I've created the following table:

https://github.com/evoskuil/libbitcoin-build/blob/master/documentation/versi
oning.pdf?raw=true

Notice that previous tags have been consistently signed and fairly
consistently applied, although there are some oversights in pkg-config
versions (and in dependency references not shown here).

The notable issue is on the libbitcoin/version1 line. Notice that the source
versions are 1.0.x when the tags transition to v2.0.x. At the same time this
lineage ended up on an independent branch because of the long run on
develop. So I made the call to name the branch version1, aligned with the
pkg-config. After that it clears up.

To resolve the inconsistencies in source configurations, versions and
dependencies we now have libbitcoin-build. This tool is applied to all
“libbitcoin” repos (although libbitcoin-server/master is presently
uncovered).

After developing libbitcoin-build and going through the GitHub release
process for bx I agree that we should primarily rely on tags for release
identification. The main issue with tags is the inability to patch a
superseded release, which is a fairly common problem. But we can certainly
defer the decision to branch until that occasion arises, using a consistent
release branch convention to do so. For the time being I’ve preserved the
version2 branches, which are not yet necessary, and I intend to phase them
out once I’ve updated libbitcoin-build.

SX is now superseded and libwallet has been moved back to spesmilo, as SX is
its only dependant. That leaves Obelisk as the sole remaining non
“libbitcoin” library. Eventually Obelisk will be superseded by
libbitcoin-server.

In general all new work should be either on a temporary feature branch or
directly on master, using pull requests against master, relying on Travis
build validation.

Eric

-----Original Message-----
From: Eric Voskuil [mailto:eric@voskuil.org]
Sent: Tuesday, December 02, 2014 3:37 PM
To: 'Noel Maersk'; libbitcoin@???
Subject: RE: [Libbitcoin] git flow, versioning, roadmap details

Hi Noel,

Thanks for the input. I've completed the build automation tooling and am
about to make the branch changes, so this is timely.

I am not attempting to keep vesions aligned across repos over time, although
there is some alignment initially. Down the road that might make sense, in a
boost sort of way.

Tagging as a release mechansim is problematic. It presumes a single branch,
which in turn precludes any changes once the release is declared. Any patch
must be applied to the latest build, forcing everyone onto latest. I've
already seen this happen to libbitcoin at least three times in the past few
months. We've had to patch downlevel for breaking changes to the stealth
protocol, openssl removal and secp256k1 breaking changes. Inevitably we end
up on a patch branch. These breaks resulted in the master branches being
patched while new development proceeded for months independently on
'develop'. This new development couldn't be merged into master (and still
can't) because it was/is both incomplete and introduces significant breaking
changes. So we've learned that we need release branches, which means we
don't need tags, and we are in fact maintaining release branches already -
just in a very ad-hoc manner.

As such I haven't paid much attention to out tags, nor do I think has anyone
else. We could branch it as version2 and put current libbitcoin on version3,
but I think that's going to introduce a release for which there is no
custmer, and therefore just add confusion. The 'products' (either in
production or about to be) that currently sit on libbitcoin are Obelisk
(which I believe covers DarkWallet), SX, BX and Airbitz. Obelisk and SX
require what is currently branched as version1 libbitcoin (what until
recently was effectively frozen as master), with SX also requiring
libwallet/version1. BX and Airbitz require what is currently branched as
version2 (recently aligned with master). If anything I would retain the v2.0
tag as a point of interest along the master branch (more below). Ideally
this would be where the version2 branch began and there would have been no
braking changes subsequently in that branch, but that's not critical at this
point if it has no dependants.

The fact that there are verison2 branches right now is transitional. We
needed to isolate breaks and allow things to keep moving. Those issues have
been resolved by splitting out libbitcoin-node and libbitcoin-blockchain
from libbitcoin. Given that version2 branches are not "released" they really
should be master (so I will be swapping them to master until released). We
really should have all new development either taking place on master or on a
feature branch. We have been using feature branches quite regularly and I
see no issues there. And it seems like we are all quite comfortable using
master as a staging are (as you describe). So really the only question is
how to indicate releases, as tags or branches (see above).

Once master is again treated as a staging area everything gets simpler.
Develop has until recently been our staging area, with master as continuous
release. This causes several problems. Not understanding this distinction,
people pull into master or make inadvertent changes. I think we all have
done it. People think they are seeing latest from master, but they are not.
And finally we cannot patch releases on a continuous release model without
forcing everyone to latest. So based on inputs from you, Amir, William and
Phillip I'm in the process of making the following changes across all repos:

* All repos have a master, which is the main staging area for changes. This
is official latest and is not considered a "release". This means that
breaking changes can be introduced at any time. This is comfortable and
minimum friction.

* At the point of release a version# branch is created (from master).
Following release the branch exists to allow for patches while not
introducing any breaking changes (i.e. no changes to public interfaces). [At
the same time we can certainly place a label on the branch point, signifying
the initial release. But any subsequent updates to the release would be
labelled on the release branch, so I don't think there is any material
benefit to this.]

* There is no perpetual develop branch. Feature branches are named
situationally and are temporary.

* For a repo that is no longer in development (patches to the release(s)
only) there will still be a master, which would, following the above rules,
remain aligned with the branch point of the latest release. However there
would not present any problem with staging patches in master and cherry
picking them into the latest release branch as approriate. It would be
simpler to not have a master on a repo that is not under development, but as
people have mentioned, the name master makes people feel good :).

This is a very simple approach and is in common use. There will however be a
little disruption as master goes from being frozen in support of
obelisk/libwallet/sx to being latest. When building these repos from now on
it will be necessary to use libbitcoin/version1. These products can't take a
dependency on libbitcoin/version2 (or master) without significant rework
(which in the case of SX has already been done, as BX, and in the case of
Obelisk is underway in libbitcoin-server/node/blockchain).

I expect to have the remaining changes completed today.

e

-----Original Message-----
From: Libbitcoin [mailto:libbitcoin-bounces@lists.dyne.org] On Behalf Of
Noel Maersk

I'm sorry to say I agree with both of you.

Eric: do you want the toolchain to have the same versionN branches for
compatible versions? Then I'd recommend making `version3` the current
about-to-be-released version, and `version4` what's to follow - since we
already have a `v2.0` tagged release of libbitcoin.

IMO having a `version1` branch that has a `v2.0` tag is more confusing
than skipping a version number for some of the tightly-coupled dependent
projects.

Keeping versions in separate branches will only be an improvement if
someone is to maintain these branches. Otherwise, versioned releases can
be pulled from github using tags, and with one less dependency (git).

Not having a `master` branch is also confusing. It's a common name for
"where we're at now", whether with or without breaking changes to
"latest stable release". It's a nice place to test for regressions and
builds on "unsupported" platforms.

On Sat, Nov 08, 2014 at 06:53:43PM -0800, Eric Voskuil wrote:
> ...
>
> Creating a release branch is a very simple means of deprecating (vs.
> obsoleting). It still allows everyone who's ready to move on to the
> new
> branch immediately and requires almost no effort to create (and if
> desired maintain) past releases. As such there's really no downside to
> this approach. Notice that bitcoind is managed in this same manner:
> https://github.com/bitcoin
>
> e
>
>
> On 11/07/2014 02:08 PM, Amir Taaki wrote:
> > We could have version branches, the reason I haven't been merging to
> > master is that it takes work and I'm breaking things a lot now.
> > Ideally once we reach the stage of a release, we'll release a bunch
> of
> > sync'ed tarballs for people who want to build.
> > My priority (as upstream developer) is lack of friction for working,
> > more bureaucracy = more overhead and less work.
> > ...