From: Jesse Luehrs Date: Fri, 19 Nov 2010 01:35:51 +0000 (-0600) Subject: update our workflow X-Git-Tag: 1.9900~29 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=4c0880b233a64c4bf359ed40cbc766517964353d;p=gitmo%2FMoose.git update our workflow --- diff --git a/lib/Moose/Manual/Contributing.pod b/lib/Moose/Manual/Contributing.pod index fae4462..642594b 100644 --- a/lib/Moose/Manual/Contributing.pod +++ b/lib/Moose/Manual/Contributing.pod @@ -62,23 +62,12 @@ L =back -=item Core Committers - people reviewing and merging a branch - -These people have worked with the Moose codebase for a while. - -They've been responsible for large features or branches and can help review -your changes and apply them to the master branch using the basic -L. - -They are also fairly well versed in Git, in order to merge the branches with -no mistakes (especially when the merge fails), and to provide advice to -contributors. - =item Cabal - people who can release moose These people are the ones who have co-maint on Moose itself and can create a release. They're listed under L in the Moose documentation. They -merge from Master to Stable. +are responsible for reviewing branches, and are the only people who are allowed +to push to stable branches. =back @@ -89,29 +78,51 @@ everyone involved. The branches below are ordered by level of stability. =over -=item Stable (refs/heads/stable) +=item stable/* + +The branch from which releases are cut. When making a new major release, the +release manager makes a new C branch at the current position +of C. For minor releases, patches will be committed to C, and +backported (cherry-picked) to the appropriate stable branch as needed. The +C branch is only updated by someone from the Cabal during a release. -The branch from which releases are cut. When making a new release, the -release manager merges from master to stable. The stable branch is only -updated by someone from the Cabal during a release. +=item master -=item Master (refs/heads/master) +The main development branch. All new code should be written against this +branch. This branch contains code that has been reviewed, and will be included +in the next major release. Commits which are judged to not break backwards +compatibility may be backported into C to be included in the next minor +release. -The branch for new development. This branch is merged into and branched from. +=item rfc/* -=item Branches (refs/heads/*) +Topic branches that are completed and waiting on review. A Cabal member will +look over branches in this namespace, and either merge them to C if +they are acceptable, or move them back to a different namespace otherwise. -Large community branches for big development "projects". +=item topic/* -=item Topics (refs/heads/topic/*) +Small personal branches that are still in progress. They can be freely rebased. +They contain targeted features that may span a handful of commits. Any change +or bugfix should be created in a topic branch. -Small personal branches that have been published for review, but can get -freely rebased. Targeted features that may span a handful of commits. +=item attic/* -Any change or bugfix should be created in a topic branch. +Branches which have been reviewed, and rejected. They remain in the repository +in case we later change our mind, or in case parts of them are still useful. + +=item abandoned/* + +Topic branches which have had no activity for a long period of time will be +moved here, to keep the main areas clean. =back +Larger, more long term branches can also be created in the root namespace (i.e. +at the same level as master and stable). This is more appropriate if multiple +people are intending to work on the branch. These branches should not be +rebased. + =head1 STANDARD WORKFLOW # update your copy of master @@ -119,47 +130,30 @@ Any change or bugfix should be created in a topic branch. git pull --rebase # create a new topic branch - git checkout -b topic/my-feature origin/master + git checkout -b topic/my-feature # hack, commit, feel free to break fast forward - git commit --amend # allowed - git rebase --interactive # allowed - git push --force origin topic/my_feature # allowed - -Then ask for a review/approval (see L), and merge -to master. If it merges cleanly and nobody has any objections, then it -can be pushed to master. - -If it doesn't merge as a fast forward, the author of the branch needs to run + git commit --amend # allowed + git rebase --interactive # allowed + git push --force # allowed + # keep the branch rebased on top of master, for easy reviewing git remote update - git rebase origin/master # or merge + git rebase origin/master + git push --force -and bring the branch up to date, so that it can be merged as a fast forward -into master. - -No actual merging (as in a human resolving conflicts) should be done when -merging into master, only from master into other branches. - -=head2 Preparing a topic branch - -Before a merge, a topic branch can be cleaned up by the author. - -This can be done using interactive rebase to combine commits, etc, or even -C to make the whole topic into a single commit. - -Structuring changes like this makes it easier to apply git revert at a later -date, and encourages a clean and descriptive history that documents what the -author was trying to do, without the various hangups that happened while they -were trying to do it (commits like "oops forgot that file" are not only -unnecessary noise, they also make running things like git bisect or git revert -harder). + # when finished, move the branch to the rfc/ namespace + git branch -m rfc/my-feature + git push + git push origin :topic/my-feature -However, by far the biggest benefit is that the number of commits that go into -master is eventually reduced, and they are simple and coherent, making it much -easier for people maintaining branches to stay up to date. +When your branch is completed, make sure it has been moved to the C +namespace and is rebased on top of master, and ask for review/approval (see +L). If it is approved, the reviewer will merge it into +C. -All large changes should be documented in L. +No actual merging (as in a human resolving conflicts) should be done when +merging into C, only from C into other branches. =head1 APPROVAL WORKFLOW @@ -170,8 +164,8 @@ guidelines that ensures all new code is properly vetted before it is merged to the master branch. It should be noted that if you want your specific branch to be approved, it is -B responsibility to follow this process and advocate for your branch. -The preferred way is to send a request to the mailing list for review/approval, +B responsibility to follow this process and advocate for your branch. The +preferred way is to send a request to the mailing list for review/approval; this allows us to better keep track of the branches awaiting approval and those which have been approved. @@ -180,7 +174,8 @@ which have been approved. =item Small bug fixes, doc patches and additional passing tests. These items don't really require approval beyond one of the core contributors -just doing a simple review. +just doing a simple review. For especially simple patches (doc patches +especially), committing directly to master is fine. =item Larger bug fixes, doc additions and TODO or failing tests. @@ -192,7 +187,7 @@ member for accuracy. TODO tests are basically feature requests, see our L section for more information on that. If your feature needs core support, create a -topic/ branch using the L and start hacking away. +C branch using the L and start hacking away. Failing tests are basically bug reports. You should find a core contributor and/or cabal member to see if it is a real bug, then submit the bug and your @@ -229,19 +224,27 @@ defend your change. =head1 RELEASE WORKFLOW + # major releases (including trial releases) git checkout master + + # minor releases + git checkout stable + # edit for final version bumping, changelogging, etc # prepare release (test suite etc) perl-reversion -bump make manifest git commit - git checkout stable - git merge master # must be a fast forward - git push both + git branch stable/2.XXYY # only for non-trial major releases shipit # does not ship the tarball, but does everything else - cpan-upload ~/shipit-dist/Moose-X.YZ.tar.gz -Development releases are made without merging into the stable branch. + # non-trial releases + cpan-upload ~/shipit-dist/Moose-2.XXYY.tar.gz + + # trial releases + cd ~/shipit-dist + mv Moose-2.XXYY.tar.gz Moose-2.XXYY-TRIAL.tar.gz + cpan-upload Moose-2.XXYY-TRIAL.tar.gz =head2 Release How-To @@ -276,21 +279,23 @@ doing the final release steps by hand. =head1 EMERGENCY BUG WORKFLOW (for immediate release) -Anyone can create the necessary fix by branching off of the stable branch: +The stable branch exists for easily making bug fix releases. git remote update - git checkout -b topic/my-emergency-fix origin/stable + git checkout -b topic/my-emergency-fix origin/master # hack git commit -Then a cabal member merges into stable: +Then a cabal member merges into C, and backports the change into +C: - git checkout stable + git checkout master git merge topic/my-emergency-fix git push + git checkout stable + git cherry-pick -x master + git push # release - git checkout master - git merge stable =head1 PROJECT WORKFLOW @@ -317,44 +322,16 @@ merged into master: (unfortunately Git will not allow C as a branch name if C is a valid ref). -=head1 THE "PU" BRANCH - -To make things easier for longer lived branches (whether topics or projects), -the 'pu' branch is basically what happens if you merge all of the branches and -topics together with master. - -We can update this as necessary (e.g. on a weekly basis if there is merit), -notifying the authors of the respective branches if their branches did not merge -(and why). - -To update 'pu': - - git checkout pu - git remote update - git reset --hard origin/master - git merge @all_the_branches - -If the merge is clean, 'pu' is updated with C. - -If the merge is not clean, the offending branch is removed from -C<@all_the_branches>, with a small note of the conflict, and we try again. - -The authors of the failed branches should be told to try to merge their branch -into 'pu', to see how their branch interacts with other branches. - -'pu' is probably broken most of the time, but lets us know how the different -branches interact. - =head1 BRANCH ARCHIVAL Merged branches should be deleted. -Failed branches may be kept, but consider moving to refs/attic/ (e.g. -http://danns.co.uk/node/295) to keep git branch -l current. +Failed branches may be kept, but should be to C to differentiate them +from in-progress topic branches. Branches that have not been worked on for a long time will be moved to -refs/abandoned/ periodically, but feel free to move the branch back to -refs/topic/ if you want to start working on it again. +C periodically, but feel free to move the branch back to C +if you want to start working on it again. =head1 TESTS, TESTS, TESTS @@ -368,8 +345,9 @@ Moose/Class::MOP and your test exercises this feature in a non-obvious way, please add some comments either near the code in question or in the test so that others know. -We also greatly appreciate documentation to go with your changes, and -an entry in the Changes file. Make sure to give yourself credit! +We also greatly appreciate documentation to go with your changes, and an entry +in the Changes file. Make sure to give yourself credit! Major changes or new +user-facing features should also be documented in L. =head1 BACKWARDS COMPATIBILITY @@ -380,16 +358,8 @@ frivolous with our changes, quite the opposite, just that we are not afraid of change and will do our best to keep it as painless as possible for the end user. -The rule is that if you do something that is not backwards compatible, you -B do I one deprecation cycle (more if it is larger change). -For really larger or radical changes dev releases may be needed as well (the -Cabal will decide on this on a case-per-case basis). - -Our policy with deprecation is that each deprecation should go through several -stages. First, we simply add a deprecation notice the documentation in -F and L. In a future release, we then make the -deprecated feature warn loudly and often so that users will have time to fix -their usages. Finally, the feature is removed in a later release. +Our policy for handling backwards compatibility is documented in more detail in +L. All backwards incompatible changes B be documented in L. Make sure to document any useful tips or workarounds @@ -403,6 +373,8 @@ Chris (perigrin) Prather Yuval (nothingmuch) Kogman +Jesse Luehrs Edoy at tozt dot netE + =head1 COPYRIGHT AND LICENSE Copyright 2009 by Infinity Interactive, Inc.