|
|
| Line 1: |
Line 1: |
| − | <!--
| |
| − | Copy/Paste colored markup for branch names:
| |
| | | | |
| − | <span style="color:#EEAD0E">feature</span>
| |
| − | <span style="color:#458B00">master</span>
| |
| − | <span style="color:#CD2626">version</span>
| |
| − | <span style="color:#00008B">staging</span>
| |
| − |
| |
| − |
| |
| − | #FIXME headline numbering?
| |
| − | -->
| |
| − |
| |
| − | If you're an experienced git user, skip to the summary.
| |
| − |
| |
| − | ==1 Release Schedule==
| |
| − | <pre>
| |
| − | <x> = time in weeks
| |
| − | vxxx = Tag for version xxx (Marks the release)
| |
| − | rest = branches
| |
| − | \ = merge (merges from version to staging/master not shown)
| |
| − | ------------------------------------------------------------------------------------ master branch. development is never stopped
| |
| − | \ <8> \
| |
| − | ------------------------------------------------------------------------------------ staging branch
| |
| − | | | | |
| |
| − | v2.062-b1 | v2.063-b1 |
| |
| − | | |
| |
| − | | <8> ---------------- 2.063 release branch
| |
| − | | | <2> |
| |
| − | | v2.063 v2.063.1
| |
| − | |
| |
| − | -------------------------------------------------------- 2.062 release branch
| |
| − | | <2> | <2> |
| |
| − | v2.062 v2.062.1 v2.062.2
| |
| − | </pre>
| |
| − |
| |
| − | A new release is made approximately every 2 months. Releases are stabilized in the <span style="color:#00008B">staging</span> branch and beta releases are tagged as part of <span style="color:#00008B">staging</span>. When a release is ready a new <span style="color:#CD2626">version</span> branch is created from <span style="color:#00008B">staging</span>. The first commit of this <span style="color:#CD2626">version</span> branch is tagged as the release (v2.0xx). Immediately after creating the <span style="color:#CD2626">version</span> branch <span style="color:#458B00">master</span> is merged into <span style="color:#00008B">staging</span>. Note: <span style="color:#458B00">master</span> is only ever merged into <span style="color:#00008B">staging</span> immediately after a major release. Then the <span style="color:#00008B">staging</span> branch is stabilizing again until the next release is made.
| |
| − |
| |
| − | Once the initial release of the <span style="color:#CD2626">version</span> branch is done, only regression fixes will be pushed to the <span style="color:#CD2626">version</span> branch, then a regression fix update is published every 2 weeks from that <span style="color:#CD2626">version</span> branch as long as it's supported (see 3.3).
| |
| − |
| |
| − |
| |
| − | 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, announced 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:#CD2626">2.061</span> is released. <span style="color:#CD2626">2.061</span> will get updates until <span style="color:#CD2626">2.062</span> is released. Then <span style="color:#CD2626">2.062</span> will get updates until <span style="color:#CD2626">2.063</span> is released etc.
| |
| − |
| |
| − | Only supported <span style="color:#CD2626">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.
| |
| − |
| |
| − | * '''<span style="color:#458B00">master</span>''': The <span style="color:#EEAD0E">feature</span> branches are merged into this branch if they are considered complete. So the <span style="color:#458B00">master</span> branch will contain new features and may have breaking changes. Regression fixes and bug fixes will be merged from <span style="color:#00008B">staging</span> into <span style="color:#458B00">master</span>.
| |
| − | <pre>
| |
| − |
| |
| − | --------------------------------------------------------\ feature64BitWindows
| |
| − | \
| |
| − | -------------------\ featureUDA \
| |
| − | \ \
| |
| − | ------------------------------------------------------------------------------------ master branch. development is never stopped
| |
| − | \ / <8> \
| |
| − | \ / \
| |
| − | ------------------------------------------------------------------------------------ staging branch
| |
| − | /
| |
| − | fix123
| |
| − | </pre>
| |
| − |
| |
| − | * '''<span style="color:#00008B">staging</span>''': Bug fixes will be pushed directly into <span style="color:#00008B">staging</span> if they are not regression fixes. To determine where a regression fix should go, see 3.1.5. <span style="color:#00008B">staging</span> usually only gets bugfix updates, but after every major release, new features are merged from master. Regression fixes will be merged from version branches into <span style="color:#00008B">staging</span>.
| |
| − | <pre>
| |
| − | ------------------------------------------------------------------------------------ master branch. development is never stopped
| |
| − | \ <8> \
| |
| − | ------------------------------------------------------------------------------------ staging branch
| |
| − | / / / / /
| |
| − | fix123 fix234 fix987 / fix999
| |
| − | /
| |
| − | ------------------------------------------------------ 2.0.62 version branch
| |
| − | /
| |
| − | regression1
| |
| − | </pre>
| |
| − |
| |
| − | * '''<span style="color:#CD2626">version branches</span>''': Once we determine it's time to do a new release, a <span style="color:#CD2626">version</span> branch is made by branching from the <span style="color:#00008B">staging</span> branch. A version branch will not receive any new features, only regression fixes. To determine to which <span style="color:#CD2626">version</span> branch regression fixes should go, see 3.1.5. <span style="color:#CD2626">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:#CD2626">version branches</span>''': Tracking the upstream <span style="color:#CD2626">version</span> branches. If you want to push a regression fix to an older release. (See 3.1.5)
| |
| − |
| |
| − | * '''bugfix branches''': based on <span style="color:#00008B">staging</span>. Used to develop bugfixes (see 3.1.4)
| |
| − |
| |
| − | ==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 small enhancement: This will go to <span style="color:#458B00">master</span>. See 3.1.3
| |
| − | * It's a bug fix: This will go straight to <span style="color:#00008B">staging</span>. See 3.1.4
| |
| − | * It's a regression fix: This will need to go to the oldest '''supported''' <span style="color:#CD2626">version</span> branch which is affected by the regression. See 3.1.5
| |
| − |
| |
| − | ==== 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 branch coolFeature
| |
| − | #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 small enhancement ====
| |
| − | We merge directly into <span style="color:#458B00">master</span>.
| |
| − |
| |
| − | 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 branch coolFeature
| |
| − | #Make your changes
| |
| − | git commit -m "Implement cool feature"
| |
| − | #Push to your fork on github
| |
| − | git push origin coolFeature
| |
| − |
| |
| − | #Now go to github and file a pull request for coolFeature. The pull request must target the master branch!
| |
| − | </source>
| |
| − |
| |
| − | ==== 3.1.4 Bug fix (not a regression!) ====
| |
| − | We need to create a local branch based on <span style="color:#00008B">staging</span>. Then file a pull request on github targeting <span style="color:#00008B">staging</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 staging #This is the branch we base bugfix on
| |
| − | git branch bugFixNNN
| |
| − | #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 staging branch!
| |
| − | </source>
| |
| − |
| |
| − | ==== 3.1.5 Regression fix ====
| |
| − | The regression fix must be pushed to the oldest, still supported <span style="color:#CD2626">version</span> branch affected by the regression. To determine if a <span style="color:#CD2626">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:#CD2626">2.063</span> is the most recent release and supported.
| |
| − | <span style="color:#CD2626">2.062</span> is the previous release and supported.
| |
| − | <span style="color:#CD2626">2.061</span> is no longer supported.
| |
| − | An regression is found that affects 2.061, 2.062, 2.063, <span style="color:#00008B">staging</span> 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:#CD2626">2.062</span> release branch.
| |
| − |
| |
| − | '''Note''': Regression fixes are always based on an <span style="color:#CD2626">version</span> branch, never on <span style="color:#00008B">staging</span> / <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 branch fixRegressionNNN
| |
| − | #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:#CD2626">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:#CD2626">2.063</span> in our example) and to <span style="color:#00008B">staging</span> and <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 staging
| |
| − | git checkout staging
| |
| − | git pull upstream staging #Fetch remote changes from upstream first
| |
| − | git merge 2.062 #Now merge 2.062 branch into staging branch
| |
| − | git push upstream staging #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 staging #Now merge staging 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:#CD2626">release</span> will be made based on <span style="color:#00008B">staging</span>.
| |
| − |
| |
| − | To start the release process (This is always done after a major release has been made) merge master into <span style="color:#00008B">staging</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 master
| |
| − | git pull upstream master
| |
| − |
| |
| − | git checkout staging
| |
| − | git pull upstream staging
| |
| − |
| |
| − | git merge master
| |
| − | git push upstream staging
| |
| − | </source>
| |
| − |
| |
| − | Once a beta release is made, the dmd staff adds a tag on <span style="color:#00008B">staging</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 staging
| |
| − | git pull upstream staging
| |
| − |
| |
| − | git tag v2.063-b1 #b1=>first beta
| |
| − | git push upstream v2.063-b1
| |
| − | </source>
| |
| − |
| |
| − | For the final release, a new version branch is created:
| |
| − | <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 staging
| |
| − | git pull upstream staging
| |
| − |
| |
| − | git branch 2.063 #replace 2.063 with the new release number
| |
| − | git push upstream 2.063
| |
| − |
| |
| − | #And make a tag
| |
| − | git tag v2.063
| |
| − | git push upstream v2.063
| |
| − | </source>
| |
| − |
| |
| − | === 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 regression fixes into this release <span style="color:#CD2626">version</span> follow the descriptions in 3.1.5
| |
| − |
| |
| − | 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>
| |
| − |
| |
| − | == 4 Short Summary ==
| |
| − | === Contributors ===
| |
| − | * Regression fixes go into <span style="color:#CD2626">version</span> branches
| |
| − | * Bug fixes go into the <span style="color:#00008B">staging</span> branch
| |
| − | * Big new features are developed in <span style="color:#EEAD0E">feature</span> branches and merged into <span style="color:#458B00">master</span>
| |
| − | * Small enhancements can go directly into <span style="color:#458B00">master</span>
| |
| − |
| |
| − | === DMD staff ===
| |
| − | * Merge regression fixes into <span style="color:#CD2626">version</span> branch asap.
| |
| − | * Merge regressions fixes from <span style="color:#CD2626">version</span> to other <span style="color:#CD2626">version</span> and to <span style="color:#00008B">staging</span> branch immediately.
| |
| − | * Merge <span style="color:#00008B">staging</span> branch into <span style="color:#458B00">master</span> regularly
| |
| − | * Merge bug fixes into <span style="color:#00008B">staging</span> regularly.
| |
| − | * Merge <span style="color:#EEAD0E">feature</span> branches into <span style="color:#458B00">master</span> on demand.
| |
| − | * Merge <span style="color:#458B00">master</span> into <span style="color:#00008B">staging</span> '''after''' every release
| |
| − |
| |
| − | == 5 Rationale ==
| |
| − | === <span style="color:#00008B">staging</span> ===
| |
| − | This setup has the advantage that <span style="color:#00008B">staging</span> stabilizes over a long time. <span style="color:#00008B">staging</span> get's a feature updates only after every major release is made. After that <span style="color:#00008B">staging</span> only recieves bug fixes. It also has the advance that bug fixes also have a clear target branch: With <span style="color:#00008B">staging</span> we can always target <span style="color:#00008B">staging</span>. Without <span style="color:#00008B">staging</span> we'd have to target the version branch of the currently stabilizing <span style="color:#CD2626">version</span> branch. But that branch changes over time, so we'd have to update github pull requests, etc.
| |
| − |
| |
| − |
| |
| − | == 6 Possible optimization ==
| |
| − | * If it turns out that <span style="color:#00008B">staging</span> does not get reasonably stable to create the release immediately from <span style="color:#00008B">staging</span> we could introduce a time span (e.g 3 weeks) between branching the new <span style="color:#CD2626">version</span> branch and releasing the version / setting the tag. In this timespan only regression fixes would be merged into the <span style="color:#CD2626">version</span> branch. After that time span the release will be tagged on the <span style="color:#CD2626">version</span> branch
| |
| − | ** additional betas can be released from the version branch during that time span
| |
| − | <pre>
| |
| − | <x> = time in weeks
| |
| − | vxxx = Tag for version xxx (Marks the release)
| |
| − | rest = branches
| |
| − | \ = merge (merges from version to staging/master not shown)
| |
| − | ---------------------------------------------------------------------------------------------- master branch. development is never stopped
| |
| − | \ <8> \
| |
| − | ---------------------------------------------------------------------------------------------- staging branch
| |
| − | | | | |
| |
| − | v2.062-b1 | v2.063-b1 |
| |
| − | | | <3> .
| |
| − | | <8> -------------------------- 2.063 release branch
| |
| − | | | | <2> |
| |
| − | | rc1 v2.063 v2.063.1
| |
| − | | <3> .
| |
| − | ------------------------------------------------------------------ 2.062 release branch
| |
| − | | | <2> | <2> |
| |
| − | v2.062-rc1 v2.062 v2.062.1 v2.062.2
| |
| − | </pre>
| |
