Kokua:Repository Strategy

Repositories
(To be written...)

gold
The central gold branch holds a reference to the latest gold version of Kokua. A gold version is the final, polished release of the viewer (e.g. "1.0.0", "1.1.0", "1.2.0"). If there are any hotfix versions afterwards (e.g. "1.0.1", "1.0.2"), the gold branch is also updated to the latest hotfix version.

The only time the contral gold branch is modified directly, is to update the version number and perform other release time tweaks. All other changes are made by merging the central release branch into the central gold branch. The viewer behavior is never modified directly on the gold branch.

release
The central release branch holds a reference to the latest non-Experimental release of Kokua, including gold versions, hotfix releases, release candidates, and betas.

The only time the central release branch is modified directly, is to update the version number and perform other release time tweaks. All other changes are made by merging the central dev branch into the central release branch immediately before release time. The viewer behavior is never modified directly on the release branch.

dev
The central dev branch is the main development branch. All topic branches are created from the central dev branch, and all topic branches are later merged back into the central dev branch. The central dev branch is merged into the central release branch immediately before release time.

The central dev branch is never modified directly. It is only modified by merging topic branches into it, and by merging release back into it immediately after release time.

exp
The central exp branch is the Experimental development branch. Topic branches are merged into the central exp branch so that they can be included in the next Experimental release, for testing. Topic branches are also merged into the central exp branch (and into the central dev branch) when the topic branch is finished.

The only time the central exp branch is modified directly, is to update the version number and perform other release time tweaks. All other changes are made by merging topic branches into the central exp branch.

The central exp branch is never merged into any other branch, ever. Not under any circumstances!

Branches in Personal Repositories
(To be written...)

dev
(To be written...)

exp
(To be written...)

Topic Branches
(To be written...)

Example
This diagram demonstrates an example scenario involving the following branches (from left to right, top to bottom):


 * G: The gold branch in the central repository.
 * R: The release branch in the central repository.
 * D: The dev branch in the central repository.
 * T1: A topic branch called topic-1, in some developer's personal repository.
 * T2: A (different) topic branch called topic-2, also in some developer's personal repository (possibly the same developer, possibly a different developer).
 * E: The exp branch in the central repository.
 * H: A hotfix branch called 1.0-hotfix. This is a special topic branch created for the purpose of fixing bugs in a gold release.



At the start of the diagram, gold, release, and dev are all identical (i.e. they refer to the exact same commit).

The following events occur in this diagram (chronologically, from top to bottom):

1. topic-1 is branched from dev and has a new commit. This new topic branch is created for a specific purpose (e.g. fixing a certain bug, or implementing a certain feature). The commit message for the first commit in this branch says at the bottom, "This marks the start of branch topic-1."

2. topic-1 is merged into exp, so that it can be tested in the wild. This merge creates a merge commit.

3. topic-2 is branched from dev and has a new commit. Like topic-1, this branch is created for a (different) specific purpose. The commit message for the first commit in this branch says at the bottom, "This marks the start of branch topic-2."

4. exp has a new commit. This marks an Experimental release. The commit updates the version number, but does not make any other changes to the viewer code.

5. topic-1 is merged back into dev. Presumably it has been tested in the Experimental release, and found to be stable enough to merge into the main line. This merge creates a merge commit, because the merge is performed with the --no-ff flag.

6. topic-2 is merged into exp, so that it can be tested in the wild. This creates a merge commit. At this point, exp contains both topic-1 and topic-2 (as they exist so far).

7. topic-2 has a new commit, perhaps a bugfix (related to this feature), polish, or further development of the feature.

8. topic-1 has a new commit, to put on the finishing touches before it is finally merged back into dev (and exp).

9. topic-1 is merged into dev and exp. This creates two merge commits, one in dev and one in exp, because the merges are performed with the --no-ff flag. The commit messages both say at the bottom, "This marks the end of branch topic-1." topic-1 is now considered finished, and can be deleted after the merging is complete. At this point, dev contains only topic-1, while exp contains topic-1 and part of topic-2.

10. dev is merged into topic-2. topic-2 now contains the final version of topic-1. Note: the only time dev should be merged into an existing topic branch is when there are changes in dev that significantly affect the development of the topic branch.

11. dev is merged into release. The commit updates the version number, but does not make any other changes to the viewer code. This marks a beta, version 1.0.0 beta 1. release then is fast-forward merged (or copied) to dev. release and dev now refer to the exact same commit.

12. topic-2 has a new commit, perhaps a bugfix (related to this feature), polish, or further development of the feature.

13. topic-2 is merged into both dev and exp. This creates two merge commits, one in dev and one in exp, because the merges are performed with the --no-ff flag. The commit messages both say at the bottom, "This marks the end of branch topic-2." topic-2 is now considered finished, and can be deleted after the merging is complete. At this point, both dev and exp are fully up to date with both topic-1 and topic-2.

14. exp has a new commit. This marks an Experimental release. The commit updates the version number, but does not make any other changes to the viewer code.

15. dev is merged into release. This merge creates a merge commit, because the merge is performed with the --no-ff flag. The commit updates the version number, but does not make any other changes to the viewer code. This marks a release candidate, version 1.0.0 RC1. release then is (possibly fast-forwarded) to dev. release and dev now refer to the exact same commit.

16. release is merged into gold, after the release candidate has been tested and found to be acceptable. This merge creates a merge commit, because the merge is performed with the --no-ff flag. The commit updates the version number, but does not make any other changes to the viewer code. This marks a gold release, version 1.0.0. gold then is merged (possibly fast-forwarded) to release, and release to dev. gold, release and dev now refer to the exact same commit.

17. 1.0-hotfix is branched from gold, to address a serious issue in version 1.0.0 that was discovered a while after release. Since there is only one issue to fix, a single commit is made directly to the 1.0-hotfix branch. (If there had been multiple issues to fix, a 1.0-hotfix branch with a new commit with the message "Created branch 1.0-hotfix." Then, multiple topic branches would be branched from 1.0-hotfix and then merged back into 1.0-hotfix.)

18. 1.0-hotfix is merged into gold. This merge creates a merge commit, because the merge is performed with the --no-ff flag. The commit updates the version number, but does not make any other changes to the viewer code. This marks a hotfix release, version 1.0.1. gold then is merged (possibly fast-forwarded) to release, and release to dev. gold, release and dev now refer to the exact same commit. 1.0-hotfix is also merged into exp, so that the issue is fixed in that branch too.