=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</APPROVAL WORKFLOW>.
-
-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<Moose/CABAL> 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
=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<stable/$version> branch at the current position
+of C<master>. For minor releases, patches will be committed to C<master>, and
+backported (cherry-picked) to the appropriate stable branch as needed. The
+C<stable> 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<stable> 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<master> 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
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</APPROVAL WORKFLOW>), 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<git merge --squash> 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<rfc/>
+namespace and is rebased on top of master, and ask for review/approval (see
+L</APPROVAL WORKFLOW>). If it is approved, the reviewer will merge it into
+C<master>.
-All large changes should be documented in L<Moose::Manual::Delta>.
+No actual merging (as in a human resolving conflicts) should be done when
+merging into C<master>, only from C<master> into other branches.
=head1 APPROVAL WORKFLOW
the master branch.
It should be noted that if you want your specific branch to be approved, it is
-B<your> 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<your> 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.
=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.
TODO tests are basically feature requests, see our L</NEW FEATURES> section
for more information on that. If your feature needs core support, create a
-topic/ branch using the L</STANDARD WORKFLOW> and start hacking away.
+C<topic/> branch using the L</STANDARD WORKFLOW> 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
=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
=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<master>, and backports the change into
+C<stable>:
- 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
(unfortunately Git will not allow C<my-project/foo> as a branch name if
C<my-project> 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<push --force>.
-
-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<attic/> 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<abandoned/> periodically, but feel free to move the branch back to C<topic/>
+if you want to start working on it again.
=head1 TESTS, TESTS, TESTS
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<Moose::Manual::Delta>.
=head1 BACKWARDS COMPATIBILITY
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<must> do I<at least> 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<Changes> and L<Moose::Manual::Delta>. 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<Moose::Manual::Support>.
All backwards incompatible changes B<must> be documented in
L<Moose::Manual::Delta>. Make sure to document any useful tips or workarounds
Yuval (nothingmuch) Kogman
+Jesse Luehrs E<lt>doy at tozt dot netE<gt>
+
=head1 COPYRIGHT AND LICENSE
Copyright 2009 by Infinity Interactive, Inc.
projects / gitmo/Moose.git / commitdiff