From: Jesse Vincent <jesse@bestpractical.com>
Date: Mon, 26 Oct 2009 20:08:19 +0000 (-0400)
Subject: Hashed out a prose description of the (largely existing) branching and topic branch... 
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=ce2a8773749b6722584a63f84a44b43287329677;p=p5sagit%2Fp5-mst-13.2.git

Hashed out a prose description of the (largely existing) branching and topic branch policy.

Wrote down the existing "no, don't mess with blead's history, bozo"
setup
---

diff --git a/pod/perlrepository.pod b/pod/perlrepository.pod
index a72be28..db7c543 100644
--- a/pod/perlrepository.pod
+++ b/pod/perlrepository.pod
@@ -675,6 +675,44 @@ And then push back to the repository:
 
   % git push
 
+
+=head1 TOPIC BRANCHES AND REWRITING HISTORY
+
+Individual committers should create topic branches under
+B<yourname>/B<some_descriptive_name>. Other committers should check with
+a topic branch's creator before making any change to it.
+
+If you are not the creator of B<yourname>/B<some_descriptive_name>, you
+might sometimes find that the original author has edited the branch's
+history. There are lots of good reasons for this. Sometimes, an author
+might simply be rebasing the branch onto a newer source point. Sometimes,
+an author might have found an error in an early commit which they wanted
+to fix before merging the branch to blead.
+
+Currently the master repository is configured to forbid non-fast-forward
+merges.  This means that the branches within can not be rebased and
+pushed as a single step.
+
+The only way you will ever be allowed to rebase or modify the history of a
+pushed branch is to delete it and push it as a new branch under the same
+name. Please think carefully about this, you may want to sequentially
+name your branches so that it is easier for others working with you to
+cherry-pick their local changes.
+
+If you want to rebase a personal topic branch, you will have to delete
+your existing topic branch and push as a new version of it.
+
+B<DO NOT, UNDER ANY CIRCUMSTANCES, SO MUCH AS THINK ABOUT TRYING THIS 
+ON BLEAD OR MAINT>
+
+We don't edit the history of the blead and maint-* branches. If a
+typo (or worse) sneaks into a commit to blead or maint-*, we'll fix
+it in another commit. 
+
+Tags in the canonical perl.git repository will never be deleted or
+modified. Think long and hard about whether you want to push a local
+tag to perl.git before doing so.
+
 =head1 COMMITTING TO MAINTENANCE VERSIONS
 
 Maintenance versions should only be altered to add critical bug fixes.