doc: describe push rules in more detail

Signed-off-by: Frantisek Hrbata <frantisek@hrbata.com>

diff --git a/Documentation/git-mr-update.txt b/Documentation/git-mr-update.txt
index b34c52549522214163c6961fdc27dc2ba9f99908..3b36b439d227736b720b86bde0a832e189025ec2 100644 (file)
--- a/Documentation/git-mr-update.txt
+++ b/Documentation/git-mr-update.txt
@@ -16,19 +16,55 @@ SYNOPSIS
 DESCRIPTION
 -----------
 This is not intended to be run directly from command line. It's the default
-push policy checker for 'gimmr'. Just create a symlink 'update' pointing to
+push policy checker for 'gimrr'. Just create a symlink 'update' pointing to
 'git-mr-update' in git's 'hooks' directory on your server.
 
+
 DEFAULT PUSH POLICY
 -------------------
-* Users listed in 'git config mr.admins' are not restricted
-* Fast-forward ref updates only
-* MR refs('head') can be created only, no updates are allowed
-* Only refs in user's namespace can be updated('tags', 'mbox')
-* Refs cannot be deleted
-* Updates to 'tags' and 'mbox' refs are checked to be in expected format
-* Only admins and user who created the MR are allowed to modify global
-  MR tags
+Users listed in 'git config mr.admins' on server are not restricted. This would
+be usually only the maintainer, who has full access to the repo. Other users
+are allowed to do fast-forward push to their namespaces only. Each user has
+it's own ref namespace under each MR namespace.
+
+Following rules are enforced for each user reference.
+
+. 'refs/mrs/<mr-sha-1>/<user>/head'
+* No updates are allowed. Once 'head' ref is created it cannot be changed.
+* The '<mr-sha-1>' part of the ref name has to match the rev this ref points to.
+* There cannot be other 'head' ref created by different '<user>' in the same
+  '<mr-sha-1>' namespace.
+
+. 'refs/mrs/<mr-sha-1>/<user>/mr'
+* No updates are allowed. Once 'mr' ref is created it cannot be changed.
+* The 'head' ref has to already exist for '<mr-sha-1>'.
+* The 'head' and 'mr' ref have to be in the same user namespace. Meaning they
+  have to be created by the same user.
+* The commit it points to has to have the 'tag' file, which is in gimrr's format
+  for tags.
+* The 'tag' file has to contain following tags: M, B, A, C, CC, AN, AE, AT.
+* 'A' tag value has to match user on the server.
+* 'M' tag value has to match rev the 'head' ref points to.
+* 'B' tag value has to be ancestor of 'A'.
+* 'C' tag value has to contain list of commits in range 'B'..'M'.
+
+. 'refs/mrs/<mr-sha-1>/<user>/tags'
+* The 'head' ref has to already exist for '<mr-sha-1>'.
+* The commit it points to has to have the 'tag' file, which is in gimrr's format
+  for tags.
+* The 'tag' file must not to contain following tags: M, B, A, C, CC, AN, AE, AT.
+* 'S' and 'D' tags can be set only by the MR author. Meaning only user with
+  'head' ref in his namespace can set these tags.
+
+. 'refs/mrs/<mr-sha-1>/<user>/mbox'
+* The 'head' ref has to already exist for '<mr-sha-1>'.
+* The commit it points to has to have the 'mbox' file, which is in gimrr's
+  format for comments.
+* The 'mbox' file has to contain 'To' and 'In-Reply-To' email header followed by
+  empty line.
+* The 'In-Reply-To' has to be in expected format and has to contain valid MR
+  rev, which has to match rev in 'head' ref in the same '<mr-sha-1>' namespace.
+
 
 SEE ALSO
 --------