Branching Strategy for Readium-2

[rkwright]

The questions is what is the approach to branching strategy overall for Readium-2. The two primary choices (though there might be others) are:

1. use the "traditional" master/development/feature approach
2. substitute a two-tiered master for a development branch

First approach

There are three basic branch/groups:

• master, which is always stable and buildable. The head of master is the latest release and is tagged as such. It has a version, which is the latest stable version identifier, e.g. 0.12
• development, which is normally quite stable and buildable, but may have some experimental or trial aspects. It's version is the master-version +1 plus the label "alpha", e.g. 0.13-alpha
• feature branches whose name have the form "feature/some-branch", e.g. "feature/non-linear-support". Feature branches do not normally have any version or label. There may be 0 or more feature/branches at any given time.

Development process is as follows:

• the master branch is created and labeled initially

• the development branch is created by branching from the master. All development is done in the development branch, which is to say that developer's commits are pushed to the development branch when they are qualified. Ideally this "qualification" is done through pull-requests, but in any case, commits are made from the developer's local copies when the code is deemed clean.

• When a feature branch is deemed ready, a pull-request is made targeting the develop branch (never the master)

• periodically, the develop branch is judged ready to be merged into the master and a release is made. At this time:

  • the code in the develop branch is merged into the master
  • the version in the master branch is bumped up
  • the head of the master branch is tagged with the new release number
  • any necessary build artifacts are built and archived
  • the version number of the develop branch is bumped up

Second approach

There are two basic branch/groups:

• master, which comprises two sections, the head, which corresponds to the develop branch in the first approach in that it is mostly stable and the uppermost (most recent) tagged section which is guaranteed stable
• feature branches whose name have the form "feature/some-branch", e.g. "feature/non-linear-support". Feature branches do not normally have any version or label. There may be 0 or more feature/branches at any given time.

Development process is as follows:

• the master branch is created and labeled initially

• there is no development branch. Instead, commits from the developers are pushed to the master branch, but the head is neither tagged nor guaranteed to be 100% stable.

• when it is time for a release,

  • the version of the master branch is bumped up
  • the head of the master branch is tagged with the new version and label.
  • any necessary build artifacts are built and archived

Subsequent, commits by developers are to the master branch, but are ahead of the master's new tag so are not part of the release

[rkwright]

After the discussion on the Readium engineering meeting on 31 October, re-opening this as it would appear we still have some open questions here - maybe a number of questions.