Message-ID: <56E5E7CF.9020207@anastigmatix.net>
Date: Sun, 13 Mar 2016 18:21:03 -0400
From: Chapman Flack <chap@anastigmatix.net>
MIME-Version: 1.0
Subject: [Pljava-dev] Second thoughts about PL/Java git branching model
Content-Type: text/plain; charset="us-ascii"

In planning a first release since moving to github and mavenizing,
I was not quite sure of the git branching model to set up. I created
a branch REL1_5_STABLE for any 1.5.* releases to exist on, by analogy
with the core PostgreSQL practice, and changed the version number from
1.5.0-SNAPSHOT to (initially) 1.5.0-BETA1 on that branch, and from
1.5.0-SNAPSHOT to 1.6.0-SNAPSHOT on the master branch, where development
intended for after 1.5.0 can happen. So, that led to a picture like this:

--.--.--(15S)--+--(16S)--> (master)
               |
	  (15S)+--(15B1)--> (REL1_5_STABLE)

As it happens, the way the core PostgreSQL team handles changes that should
apply to both the master/trunk and a _STABLE branch is by creating distinct
commits on each, that apply the same change. I wanted to use a more git-flow
inspired technique, where change branches originate at the point where the
release branch diverged, and can be cleanly merged into both branches.
That led to:

--.--.--(15S)--+--(16S)--->---------->----> (master)
               |         /          /
	       +--chg1--<          /
	       +---------\--chg2--<
	       |          \        \
	       +-(15B1)---->-------->--(15B2)--> (REL1_5_STABLE)

but, with several changes, that has become unpleasantly bushy when viewed
as a graph. In retrospect, there are several things I don't like about it:

1. Along the branch REL1_5_STABLE, the version string always names a
   release version, even in intermediate commits. That's true for the core
   PostgreSQL repo too, but arguably it could be a trap for the unwary, who
   could build a version that isn't as released, but looks as if it is.

2. The every-change-starts-from-the-branch-point approach works well for
   several unrelated changes, but not for inherently cumulative things
   like release-notes updates, etc.

3. The GitHub pull-request mechanism isn't easily applied to this structure.


I propose something different for the next time a release 1.x.0 is ready
to branch off from master at 1.x.0-SNAPSHOT:

1. Unless a better name is suggested, the new branch may still be called
   REL1_x_STABLE, but the version string will never be changed on this
   branch; it will remain frozen at 1.x.0-SNAPSHOT as it was when branched.

2. The version string on master will change to 1.(x+1).0-SNAPSHOT.

3. Changes intended only for the future version can be made as pull
   requests against master, as they have been in the past. Changes
   intended for both the current and future version can be made as
   pull requests against REL1_x_STABLE; the GitHub UI does allow that,
   and git can merge them both into that branch and into master.

4. Actual releases won't be on any branch; they will be tagged and
   accessible only by tag. Assuming HEAD points to a commit on
   REL1_x_STABLE that should become a release, that can be done by:

   a. enter detached-HEAD mode (git checkout HEAD~0)
   b. set the release version string (mvn versions:set -DnewVersion=...)
   c. commit (accept the detached-head warning)
   d. make an annotated tag (git tag -a V1_x_ywhatever)
   e. push that tag to the public repo (git push origin tag V1_x_ywhatever)
   f. return to the branch (git checkout REL1_x_STABLE) ...
      where the version string remains 1.x.0-SNAPSHOT.

I've checked that GitHub behaves reasonably when pushed a tag in isolation;
it shows up in the list of releasable tags just like any other. It doesn't
show up in the "network" graph, which only shows branches.

So that would lead to a structure like this:

                         +newfeature1+	   +newfeature2+
                         |           |	   |	       |
--.--.--(16S)--+--(17S)--+-----+-----+---+-+-----------+--> (master)
               |              /         /
	       +--+---+------+--+------+---+---+----------> (REL1_6_STABLE)
	          |   +-chg1-+  +-chg2-+   |   +-chg...
		(160)                    (161)
		  |                        |
		 tag                      tag

... which I think will be more comprehensible and easier to work with.

As for the current REL1_5_STABLE branch, without changing any published
history, I propose to approximate having thought of this earlier,
by pushing a commit at the current head of that branch to change the
version string *back* to 1.5.0-SNAPSHOT, then following the procedure above
when tagging more releases from it.

-Chap
_______________________________________________
Pljava-dev mailing list
Pljava-dev@lists.pgfoundry.org
http://lists.pgfoundry.org/mailman/listinfo/pljava-dev