User:Jpf/Release Process

1 Release Schedule

<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

Approximately every 2 months a new version branch is created from the master branch. This version branch will only receive bug fixes and regression fixes for the next 3 weeks. Then a release is prepared from that version branch. These releases include bug fixes and new/deprecated/removed features. Main development happens parallel on master. Once the initial release of the version branch is done, only regression fixes will be pushed to the version branch, then a regression fix update is published every 2 weeks from that version 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 feature branch may need it's own beta release before being merged into master. 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 2.061 is released. 2.061 will get updates until 2.062 is released. Then 2.062 will get updates until 2.063 is released etc.

Only supported releases receive minor update releases.

2 Branching model

Official branches

The following branches will be available on the official (upstream) dmd, druntime and phobos repositories:

• feature branches: New features, in general, are not developed directly on the master branch, but in a dedicated feature 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 feature branch. When the feature's implementation is more-or-less complete, the feature branch will be merged into the master branch. Huge bug fixes could also get a feature branch if some sort of collaboration is needed before the bug fix is finished. Usually bug fixes are directly merged into master or a version branch though (see 3.1.3).

• master: Most development takes place on the master branch. The feature branches are merged into this branch if they are considered complete. Bug fixes can be pushed directly into master if they are not regression fixes. To determine where a regression fix should go, see 3.1.4. So the master branch will contain new features and may have breaking changes.

• version branches: Once we determine it's time to do a new release, a version branch is made by branching from the master branch. A version branch will not receive any new features, only non-breaking, critical bugfixes. To determine whether bug fixes should go to master or a version branch, see 3.2. Version 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:

• feature branches: Tracking upstream feature branches. You only need a feature branch if you want to work on that feature. To work on a feature, make changes to the feature branch, push to your repository and file a pull request on github targeting the feature branch

• master: Tracking the upstream master branch. New feature branches should be branched from this branch.

• version branches: Tracking the upstream version branches. If you want to push a regression / bug fix to an older release. (See 3.1.4)

• bugfix branches: based on master or version 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 feature branch. See 3.1.2
• It's a bug fix or small feature (but not a regression): This will go straight to master. Se 3.1.3
• It's a regression fix: This will need to go to the oldest supported version 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 master. As a normal user you can't create feature branches on the official repository though.

Step-By-Step: The one implementing the feature has to do this:

#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)!

If someone requests a new feature branch the dmd staff has to do this:

#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

3.1.3 Bug fix (not a regression!)

We need to create a local branch based on master. Then file a pull request on github targeting master.

Step-By-Step:

#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!

3.1.4 Regression fix

The regression fix must be pushed to the oldest, still supported version branch affected by the regression. To determine if a version 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): 2.063 is the most recent release and supported. 2.062 is the previous release and supported. 2.061 is no longer supported. An regression is found that affects 2.061, 2.062, 2.063 and master.

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 2.062 release branch.

Note: Regression fixes are always based on an version branch, never on master!

Step-By-Step: The one fixing the regression has to do this:

#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!

The dmd staff now has to merge that pull request. The regression fix will be applied to the 2.062 branch. The dmd staff now also has to make sure this fix is also applied to all newer release branches (2.063 in our example) and to master.

#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

3.2 Preparing a new major release

As described in 1 every 2 months a new major release will be prepared based on master.

To start the release process:

#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

To put further changes / bug fixes into this release version follow the descriptions in 3.1.4 but always use this new 2.063 branch as the base branch. (Note: in this case the dmd staff only has to merge into 2.063 and master as there will be no new version between 2.063 and master)

Once a beta release is made, the dmd staff adds a tag!

#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

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 version follow the descriptions in 3.1.4)

Once the release is made, the dmd staff adds a tag!

#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