View source for User:Jpf/Release Process

<!--
Copy/Paste colored markup for branch names:

<span style="color:#EEAD0E">feature</span>
<span style="color:#458B00">master</span>
<span style="color:#68228B">version</span>


#FIXME headline numbering?
-->

==1 Release Schedule==
<pre>
<x> = time in weeks
vxxx = Tag for version xxx (Marks the release)
rest = branches
--------------------------------------------------------------------------- master branch. development is never stopped
  |    <8>     |2.063
  |            ------------------------------------------------------------ 2.063 release branch
  |                            <3>                       |   <2>  |
  |                                                   v2.063    v2.063.1
  |2.062
  ------------------------------------------------------------------------- 2.062 release branch
    <3>   |  <2>  |  <2>   |    <2>     |
       v2.062  v2.062.1  v2.062.2    v2.062.3
</pre>

Approximately every 2 months a new <span style="color:#68228B">version</span> branch is created from the <span style="color:#458B00">master</span> branch. This <span style="color:#68228B">version</span> branch will only receive bug fixes and regression fixes for the next 3 weeks. Then a release is prepared from that <span style="color:#68228B">version</span> branch. These releases include bug fixes and new/deprecated/removed features. Main development happens parallel on <span style="color:#458B00">master</span>. Once the initial release of the <span style="color:#68228B">version</span> branch is done, only regression fixes will be pushed to the <span style="color:#68228B">version</span> branch, then a regression fix update is published every 2 weeks from that <span style="color:#68228B">version</span> branch as long as it's supported (see 3.3). 

A new compiler major release is therefore published approximately every 2 months.

Feature Previews: A <span style="color:#EEAD0E">feature</span> branch may need it's own beta release before being merged into <span style="color:#458B00">master</span>. These are unplanned, announce on the NG, and highly volatile.

''As an example we would see these releases for things like 64bit support and User Defined Attributes.''

=== Support time for compilers ===
Currently only the most recent major release is supported. (This might change in the future)

As an example:
version <span style="color:#68228B">2.061</span> is released. <span style="color:#68228B">2.061</span> will get updates until <span style="color:#68228B">2.062</span> is released. Then <span style="color:#68228B">2.062</span> will get updates until <span style="color:#68228B">2.063</span> is released etc.

Only supported <span style="color:#68228B">releases</span> receive minor update releases.

==2 Branching model==

=== Official branches ===
The following branches will be available on the official (upstream) [https://github.com/D-Programming-Language/dmd dmd], [https://github.com/D-Programming-Language/druntime druntime] and [https://github.com/D-Programming-Language/phobos phobos] repositories:

* '''<span style="color:#EEAD0E">feature branches</span>''': New features, in general, are '''not''' developed directly on the <span style="color:#458B00">master</span> branch, but in a dedicated <span style="color:#EEAD0E">feature</span> branch. An example for such a branch would be an ''UDA'' branch for user defined attributes. Contributors can collaborate on the feature by opening pull request targeting that <span style="color:#EEAD0E">feature</span> branch. When the feature's implementation is more-or-less complete, the <span style="color:#EEAD0E">feature</span> branch will be merged into the <span style="color:#458B00">master</span> branch. Huge bug fixes could also get a <span style="color:#EEAD0E">feature</span> branch if some sort of collaboration is needed before the bug fix is finished. Usually bug fixes are directly merged into <span style="color:#458B00">master</span> or a <span style="color:#68228B">version</span> branch though (see 3.1.3).

* '''<span style="color:#458B00">master</span>''': Most development takes place on the <span style="color:#458B00">master</span> branch. The <span style="color:#EEAD0E">feature</span> branches are merged into this branch if they are considered complete. Bug fixes can be pushed directly into <span style="color:#458B00">master</span> if they are not regression fixes. To determine where a regression fix should go, see 3.1.4. So the <span style="color:#458B00">master</span>  branch will contain new features and may have breaking changes.

* '''<span style="color:#68228B">version branches</span>''': Once we determine it's time to do a new release, a <span style="color:#68228B">version</span>  branch is made by branching from the <span style="color:#458B00">master</span>  branch. A version branch will not receive any new features, only non-breaking, critical bugfixes. To determine whether bug fixes should go to <span style="color:#458B00">master</span>  or a <span style="color:#68228B">version</span>  branch, see 3.2. <span style="color:#68228B">Version</span>  branches are used to support the version for an extended period of time to enable updated minor releases which fix regressions.

=== Suggested local branches ===
How user repositories are managed is up to the end user, but we propose this branches:
* '''<span style="color:#EEAD0E">feature branches</span>''': Tracking upstream <span style="color:#EEAD0E">feature</span> branches. You only need a <span style="color:#EEAD0E">feature</span> branch if you want to work on that feature. To work on a feature, make changes to the <span style="color:#EEAD0E">feature</span> branch, push to your repository and file a pull request on github '''targeting the <span style="color:#EEAD0E">feature</span> branch'''

* '''<span style="color:#458B00">master</span>''': Tracking the upstream <span style="color:#458B00">master</span>  branch. New feature branches should be branched from this branch.

* '''<span style="color:#68228B">version branches</span>''': Tracking the upstream <span style="color:#68228B">version</span>  branches. If you want to push a regression / bug fix to an older release. (See 3.1.4)

* '''bugfix branches''': based on <span style="color:#458B00">master</span> or <span style="color:#68228B">version</span>  branch. Used to develop bugfixes (see 3.1.3)

==3 Git workflow==

=== 3.1 Working on code updates ===

==== 3.1.1 What type of update? ====
To determine to which branch an update should be made, we have to consider the type of the change:

* It's a new, big feature: This will need to get a <span style="color:#EEAD0E">feature</span> branch. See 3.1.2
* It's a bug fix or small feature (but not a regression): This will go straight to <span style="color:#458B00">master</span>. Se 3.1.3
* It's a regression fix: This will need to go to the oldest '''supported''' <span style="color:#68228B">version</span> branch which is affected by the regression. See 3.1.4

==== 3.1.2 New feature / Big enhancement ====
We need to create a new branch based on <span style="color:#458B00">master</span>. As a normal user you can't create <span style="color:#EEAD0E">feature</span> branches on the official repository though.

Step-By-Step:
The one implementing the feature has to do this:
<source lang="bash">
#We use your own fork repository, not the official one!!!!
git clone git://github.com/yourname/dmd.git
git checkout master #This is the branch we base feature
git checkout -b coolFeature # Create and checkout new branch
#Make your changes
git commit -m "Implement cool feature"
#Push to your fork on github
git push origin coolFeature

#Now request in the digitalmars.D newsgroup that someone creates a coolFeature feature branch on the official repository.

#Now go to github and file a pull request for coolFeature. The pull request must target the new official feature branch (here also called coolFeature)!
</source>

If someone requests a new <span style="color:#EEAD0E">feature</span> branch the dmd staff has to do this:
<source lang="bash">
#This time we need access to the official repository. We clone our user fork and add a remote
git clone git://github.com/yourname/dmd.git
git remote add upstream git://github.com/D-Programming-Language/dmd.git

git checkout master #This is the branch we base features on
git pull upstream master #Fetch changes from upstream

git branch coolFeature #Use a useful name
git push upstream coolFeature
</source>

==== 3.1.3 Bug fix (not a regression!) ====
We need to create a local branch based on <span style="color:#458B00">master</span>. Then file a pull request on github targeting <span style="color:#458B00">master</span>.

Step-By-Step:
<source lang="bash">
#We use your own fork repository, not the official one!!!!
git clone git://github.com/yourname/dmd.git
git checkout master #This is the branch we base bugfix on
git checkout -b bugFixNNN # Create and checkout new branch
#Make your changes
git commit -m "Implement bugfix #NNN"
#Push to your fork on github
git push origin bugFixNNN

#Now go to github and file a pull request for bugFixNNN. The pull request must target the master branch!
</source>

==== 3.1.4 Regression fix ====
The regression fix must be pushed to the oldest, still supported <span style="color:#68228B">version</span> branch affected by the regression. To determine if a <span style="color:#68228B">version</span> is still supported, see 1.1.

As an example (this doesn't match with 1.1 as we need a more complicated setup to describe the concept):
<span style="color:#68228B">2.063</span> is the most recent release and supported.
<span style="color:#68228B">2.062</span> is the previous release and supported.
<span style="color:#68228B">2.061</span> is no longer supported.
An regression is found that affects 2.061, 2.062, 2.063 and <span style="color:#458B00">master</span>.

2.061 is no longer supported, so the oldest supported and affected release is 2.062. Therefore the regression fix has to be made on the <span style="color:#68228B">2.062</span> release branch.

'''Note''': Regression fixes are always based on an <span style="color:#68228B">version</span> branch, never on <span style="color:#458B00">master</span>!

Step-By-Step:
The one fixing the regression has to do this:
<source lang="bash">
#We use your own fork repository, not the official one!!!!
git clone git://github.com/yourname/dmd.git
git checkout 2.062 #This is the branch we base our fix on
git checkout -b fixRegressionNNN # Create and checkout new branch
#Edit and fix the regression
git commit -m "Fix regression #nnn"
#Push to your fork on github
git push origin fixRegressionNNN
#Now go to github and file a pull request for fixRegressionNNN. The pull request must target our base branch, e.g. 2.062!
</source>

The dmd staff now has to merge that pull request. The regression fix will be applied to the <span style="color:#68228B">2.062</span> branch. The dmd staff now also has to make sure this fix is also applied to all newer release branches (<span style="color:#68228B">2.063</span> in our example) and to <span style="color:#458B00">master</span>.
<source lang="bash">
#This time we need access to the official repository. We clone our user fork and add a remote
git clone git://github.com/yourname/dmd.git
git remote add upstream git://github.com/D-Programming-Language/dmd.git

git checkout 2.062 #This is the branch the fix was based on
git pull upstream 2.062 #Fetch changes from upstream

#Repeat for all newer release branches
git checkout 2.063
git pull upstream 2.063 #Fetch remote changes from upstream first
git merge 2.062 #Now merge 2.062 branch into newer branch
git push upstream 2.063 #Now publish those changes

#We have to repeat that for master
git checkout master
git pull upstream master #Fetch remote changes from upstream first
git merge 2.062 #Now merge 2.062 branch into master branch
git push upstream master #Now publish those changes
</source>

=== 3.2 Preparing a new major release ===
As described in 1 every 2 months a new major <span style="color:#68228B">release</span> will be prepared based on <span style="color:#458B00">master</span>.

To start the release process:
<source lang="bash">
#This time we need access to the official repository. We clone our user fork and add a remote
git clone git://github.com/yourname/dmd.git
git remote add upstream git://github.com/D-Programming-Language/dmd.git

git checkout master
git pull upstream master

git branch 2.063 #replace 2.063 with the new release number
git push upstream 2.063
</source>

To put further changes / bug fixes into this release <span style="color:#68228B">version</span> follow the descriptions in 3.1.4 but always use this new <span style="color:#68228B">2.063</span> branch as the base branch.
(Note: in this case the dmd staff only has to merge into 2.063 and <span style="color:#458B00">master</span> as there will be no new <span style="color:#68228B">version</span> between 2.063 and <span style="color:#458B00">master</span>)

Once a beta release is made, the dmd staff adds a tag!
<source lang="bash">
#This time we need access to the official repository. We clone our user fork and add a remote
git clone git://github.com/yourname/dmd.git
git remote add upstream git://github.com/D-Programming-Language/dmd.git

git checkout 2.063
git pull upstream 2.063

git tag v2.063-b1 #b1=>first beta
git push upstream v2.063-b1
</source>

For a real release, use the above instructions with the correct tag name (v2.063 / v2.063.1 / ...)

=== 3.3 Preparing a new minor release ===
As described in 1 every 2 weeks  a new minor release will be prepared for all supported releases.

To put further changes / bug fixes into this release <span style="color:#68228B">version</span> follow the descriptions in 3.1.4)

Once the release is made, the dmd staff adds a tag!
<source lang="bash">
#This time we need access to the official repository. We clone our user fork and add a remote
git clone git://github.com/yourname/dmd.git
git remote add upstream git://github.com/D-Programming-Language/dmd.git

git checkout 2.063 #checkout the base branch where a new release is made
git pull upstream 2.063

git tag v2.063.1 #.1=>first minor update
git push upstream v2.063.1
</source>