|
|
| (35 intermediate revisions by 9 users not shown) |
| Line 1: |
Line 1: |
| − | This page is intended to serve as a working paper to capture the essential aspects of a current discussion on the D forum concerning an improved D development and release process. As such, it should not be taken as official (until approved by Andrei), but it is to serve as a centralized location for the current proposal, so that the details won't be scattered throughout multiple disjoint forum messages and ultimately lost in the mists of time.
| + | #REDIRECT [[DIP75]] |
| − | | |
| − | To keep things civil, the convention is that if something on this page doesn't match how you understand it should be, you should start a discussion on the [[Talk:Release Process|talk page]] before making the change.
| |
| − | | |
| − | ==Goals==
| |
| − | | |
| − | * To provide D users with a stable version of D that receives only critical bugfixes, that they can build on
| |
| − | * To provide a place for adequate testing of new features before they are officially included in D
| |
| − | * To allow the D developers to continue to develop the language without being hampered by the fear of breaking large amounts of existing code
| |
| − | | |
| − | ==Issues==
| |
| − | | |
| − | Here are some higher-level issues that need to be considered:
| |
| − | * What branches should there be, and how they should be used
| |
| − | * How long each branch should be maintained, etc.
| |
| − | ** How many release branches should be maintained (i.e. receive bugfixes) at one time?
| |
| − | ** How long should a release branch be maintained?
| |
| − | ** Should there be overlap between two maintained release branches to allow users to upgrade their codebases?
| |
| − | ** How long should a staging branch take to be deemed sufficiently-stable?
| |
| − | * How the chosen branching model satisfies the above mentioned goals.
| |
| − | | |
| − | ==Branching model==
| |
| − | | |
| − | The following branches are proposed:
| |
| − | | |
| − | * '''master''': Development takes place on the master branch. The master branch can add new features and may have breaking changes.
| |
| − | | |
| − | * '''feature branches''': New features, in general, are '''not''' developed directly on the master branch, but in a dedicated feature branch. Only when the feature's implementation is more-or-less complete, it will be merged into the master branch.
| |
| − | | |
| − | * '''staging''': Once development has stabilized enough for a wider audience, it is merged into the staging branch. The staging branch will only receive bugfixes. No more new features are allowed. The purpose of the staging branch is to test new features extensively before releasing them.
| |
| − | | |
| − | * '''release branches''': Once the staging branch is deemed sufficiently-tested, a release is made by branching from the staging branch and tagging. A release branch will not receive any new features, only non-breaking, critical bugfixes.
| |
| − | | |
| − | ==Git workflow==
| |
| − | | |
| − | === Release a new version of D ===
| |
| − | | |
| − | The staging branch in git contains a version in stabilization. This version will be the next release of D. When it is judged stabilized enough to be released, a branch is created for this new release. The name of the branch is D2.N+1, where N is the previous version of D2 .
| |
| − | | |
| − | <source lang="bash">git checkout staging
| |
| − | git checkout -b 2.N+1</source>
| |
| − | | |
| − | Then, a tag is created.
| |
| − | | |
| − | <source lang="bash">git tag 2.N+1.0</source>
| |
| − | | |
| − | Packaging is done as usual based on the content of the tag.
| |
| − | | |
| − | Now that the release is done, we must prepare for the next release ! The current dev version, which is in master branch will be merged into staging to be stabilized.
| |
| − | | |
| − | <source lang="bash">git checkout staging
| |
| − | git merge master</source>
| |
| − | | |
| − | ''XXX: Should we rebase here ? It make the branch tree more simple, but is more painful''
| |
| − | | |
| − | At this point, staging receive bug fixes and the cycle start again.
| |
| − | | |
| − | === Release a revision of a released version of D ===
| |
| − | | |
| − | A revision can be published on an already released version of D. Revision include bug fixes, but no new feature. We supposed bug fixes has been included into branch 2.N where N is the released version of D we want to update. M is the last revision number that have been published.
| |
| − | | |
| − | <source lang="bash">git checkout 2.N
| |
| − | git tag 2.N.M+1</source>
| |
| − | | |
| − | Packaging is done as usual based on the content of the tag.
| |
| − | | |
| − | === Working on a Bug fix ===
| |
| − | | |
| − | Bug fix is based on the lower version where the bug exists. Let's assume that this version is N. The development is done in it's own branch.
| |
| − | | |
| − | <source lang="bash">git checkout 2.N
| |
| − | git checkout -b bugXXXXXX</source>
| |
| − | | |
| − | Now you are ready to work hard to fix that nasty bug. The branch you are based on shouldn't change a lot (it only receive bug fixes), but make sure you keep in sync with the branch :
| |
| − | | |
| − | <source lang="bash">git checkout bugXXXXXX
| |
| − | git rebase 2.N</source>
| |
| − | | |
| − | At this point, conflict may happen, this is up to you to solve them. Hopefully, this type of branch is stable and this should not occur often.
| |
| − | | |
| − | When the fix is ready, push ! Then go on github and propose a pull request.
| |
| − | | |
| − | === Merging bug fixes ===
| |
| − | | |
| − | Bug fixes are based on the smaller relevant version. The merging process is a little complex, but can be automated. Here is how it is done :
| |
| − | | |
| − | <source lang="bash">git checkout 2.N-1 # During overlap of stable branches
| |
| − | git merge bugXXXXXX
| |
| − | git checkout 2.N
| |
| − | git merge bugXXXXXX
| |
| − | #...
| |
| − | git checkout staging
| |
| − | git merge bugXXXXXX
| |
| − | git checkout master
| |
| − | git merge bugXXXXXX</source>
| |
| − | | |
| − | It is up to the bug fixer to solve conflict that may occur in merging up to staging. It is up to the developer that created the conflicting feature to resolve the conflict in staging or master.
| |
| − | | |
| − | === Working on a new feature ===
| |
| − | | |
| − | New feature are based on master. You will do your own branch to develop the feature, and propose it to be merged into master. In order to make the merge easy, it is your responsibility to ensure that your feature is rebased on master and that conflict are solved.
| |
| − | | |
| − | <source lang="bash">git checkout master
| |
| − | git checkout -b myfeature</source>
| |
| − | | |
| − | Now you are ready to work on the wonderful feature you have in mind. During your development, you have to keep in sync with master. This is how it is done :
| |
| − | | |
| − | <source lang="bash">git checkout myfeature
| |
| − | git rebase master</source>
| |
| − | | |
| − | At this point, conflict may happen, this is up to you to solve them (Note, we should write something on that).
| |
| − | | |
| − | When the feature is ready, push ! Then go on github and propose a pull request.
| |
| − | | |
| − | === How synchronise your local git repo with the official DPL repo ===
| |
| − | | |
| − | The following commands all use the '''phobos''' repo. In order to use any of the other repos, simply change "'''phobos'''" to "'''dmd'''" or whichever else.
| |
| − | | |
| − | We are also assuming that your local repo was created using the following command or similar.
| |
| − | | |
| − | <source lang="bash">git clone git@github.com:YourUsername/phobos.git</source>
| |
| − | | |
| − | In order to keep your local git repo synchronised with the official DPL repo, you first need to add the DPL repo as a remote. To do this, enter this command:
| |
| − | | |
| − | <source lang="bash">git remote add official git://github.com/D-Programming-Language/phobos.git</source>
| |
| − | | |
| − | This will add tracking to the official repo for phobos, under the name 'official'.
| |
| − | | |
| − | Now, to fetch the latest official commits and changes, it is a simple matter of doing a fetch on that repo.
| |
| − | | |
| − | <source lang="bash">git fetch official</source>
| |
| − | | |
| − | This will fetch all the commits, branches, and reachable tags. The difficult part is then keeping your branches in sync with the official ones. This can be accomplished using a rebase, solving any conflicts as you go.
| |
| − | | |
| − | <source lang="bash"># First hop onto your branch
| |
| − | git checkout yourbranch
| |
| − | # then rebase onto the official master
| |
| − | git rebase -i official/master</source>
| |
