Development Process

The long feature freeze currently required to stabilize the codebase before a release has an ill effect on the momentum of the development efforts as a whole. To alleviate this effect, here is a proposal for an altered development process that does away with the need for a feature freeze by branching the release off of the bleed branch before a release and then stabilizing that branch, while development can continue unhindered on the bleed branch.

The development cycle will be split into two phases, pre-feature freeze and feature freeze.

Pre-feature freeze, things will mostly work just as they do now, with one notable exception: changelog entries for merged PRs will have to go on a new changelog page, development changelog. The regular changelog page will still show the changelog of the current stable release during this time. That distinction is needed because the build process for the playtest and release packages retrieves the changelog in real time from the wiki, so it must not contain entries from the ongoing bleeding-edge development.

At the beginning of the feature freeze, a new branch will be split off from bleed for the upcoming release. It should be named prep-YYMM, with YYMM being the year and month of the date that the split happens, since we do not know the name of the release in advance, which would otherwise have been the obvious choice. At the same time, the following steps need to happen:

• archive last release's changelog on the historical changelogs page.
• move the contents of bleed's Changelog to the release changelog page.

As the feature freeze is in effect, only fixes should go to the prep branch, while bleed is open for anything. During this time, maintainers should take care to identify fixes filed against the bleed branch that are relevant for the release being prepared. These should be tagged with a "Stable" label. This label lets a maintainer know that the PR should receive special handling:

1. It identifies PRs that should be merged into both bleed and the prep branch.
2. It signals that the changelog entry for this PR should go on the regular Changelog page, not bleed's, in order to keep the entry from ending up in the changelog of two different releases.

There will be situations where a fix should only be applied to the prep branch. In those cases a PR should be filed directly against the prep branch, and the PR be tagged with a "Stable" label as usual.

Maintainers that merge a PR marked with "Stable" into bleed should also take care of merging it into the prep branch. To do so, they should fetch and checkout the prep branch on their local machine and cherry-pick(!) the commits from the PR. Afterwards the local branch should be pushed back to the upstream repository. Do not use force-push to avoid losing changes when multiple maintainers merge PRs at the same time. After pushing, a changelog entry should be made on the regular changelog page and a comment with a link to that changelog diff be left on the PR. See below for examples.

Playtests and releases will be tagged on the prep branch. For convenience, the tagged commit should be (force-)pushed to the next or master branches as well, for playtests and releases respectively, as is it practice now. The first playtest would probably coincide with splitting off the prep branch.

After the release, the prep branch should be left around until at least the next release has been made, but can ultimately be deleted.

Things to be aware of

• Testing effort will be split across two branches, and care should be given to decide if a fix is needed only for bleed or for prep as well.
• The tags for releases and playtests will no longer be found in bleed's history.
• The history of the master branch will likely only contain the playtest and release tags of the last cycle.
• The history of the next branch will likely only contain the playtest tags of the last cycle.
• Depending on the tested range, git bisect may work a bit differently when it needs to bisect across two branches. The first thing it asks the user for is to verify whether the commit where the two branches diverged is a good or a bad commit. After that, the bisect continues as normal.

How to apply PRs to the prep branch

💡 ProTip! Add fetch = +refs/pull/*/head:refs/remotes/upstream/pr/* under [remote "upstream"] in your git/.config file.

git cherry-pick

This works well when a pull consists of only a single commit.

$ git fetch upstream
$ git checkout -B prep-YYMM upstream/prep-YYMM
$ git cherry-pick pr/1234   # if the PR is a single commit and you set up pull request checkout
$ git cherry-pick commitA   # or if it contains multiple
$ git cherry-pick commitB   # "
$ git cherry-pick commitC   # "
$ git push upstream HEAD

git apply-mail

Despite its name, git am can be used to easily apply a series of patches downloaded from Github, and should probably be the preferred way to apply PRs to prep. It even works with patches containing binary files.

$ git fetch upstream
$ git checkout -B prep-YYMM upstream/prep-YYMM
$ wget -q -O - https://github.com/openra/openra/pull/1234.patch | git am
$ curl -Lso - https://github.com/openra/openra/pull/1234.patch | git am
$ git push upstream HEAD