"D" must be combined with RW or RW+ (warning: minor backward compat breakage)

Having to specify "D" separately from RW or RW+ was cumbersome, and
although I don't actually use this feature, I can see the point.

One way to think of this is:

  - RW and RW+ were the only existing branch level rights
  - it doesnt make sense to have D rights without W (hence RW) rights
  - so we simply suffix a D to these if required.

Thus you can have RW, RW+, RWD, RW+D.

I hope the (hopefully few) of you who have started to use this feature
will convert your configs when you next upgrade to "pu".

I now regret pushing the previous syntax to master too quickly -- lots
of people use master only, and on the next promotion of pu the syntax
will change.  To reduce this exposure, this change will be promoted to
master very soon.

conf/example.conf

@@ -67,13 +67,13 @@
 #   start line:
 #       repo [one or more repos and/or repo groups]
 #   followed by one or more permissions lines:
-#       (C|D|R|RW|RW+) [zero or more refexes] = [one or more users]
+#       (C|R|RW|RW+|RWD|RW+D) [zero or more refexes] = [one or more users]
 
-# there are 5 types of permissions: R, RW, and RW+ are simple (the "+" means
+# there are 6 types of permissions: R, RW, and RW+ are simple (the "+" means
 # permission to "rewind" -- force push a non-fast forward to -- a branch).
 # The C permission is described in doc/4-wildcard-repositories.mkd.  The D
-# permission is described in doc/3-faq-tips-etc.mkd, in the "advanced
-# features" section.
+# addition to RW/RW+ is described in doc/3-faq-tips-etc.mkd, in the section on
+# "separating delete and rewind rights".
 
 # how permissions are matched:
 #     - user, repo, and access (W or +) are known.  For that combination, if

doc/3-faq-tips-etc.mkd

@@ -18,7 +18,7 @@ In this document:
           * two levels of access rights checking
           * better logging
           * "exclude" (or "deny") rules
-          * the "D" permission -- separating delete and rewind rights
+          * separating delete and rewind rights
           * file/dir NAME based restrictions
           * delegating parts of the config file
       * convenience features
@@ -367,7 +367,7 @@ And here's how it works:
     before the third one, and it has a `-` as the permission, so the push
     fails
 
-#### the "D" permission -- separating delete and rewind rights
+#### separating delete and rewind rights
 
 Since the beginning, `RW+` meant being able to rewind *or* delete a ref.  My
 stand is that these two are fairly similar, and infact a rewind is almost the
@@ -379,13 +379,15 @@ situations where one of them should be restricted more than the other.
 ([Arguments][sdrr] exist for both sides: restrict delete more than rewind, and
 vice versa).
 
-So we now allow these two rights to be separated.  Just use the new `D`
-permission anywhere in the config for the repo, and instantly all `RW+`
-permissions (for that repo) cease to permit deletion of the ref matched.
+So we now allow these two rights to be separated.  Here's how:
 
-This provides the *greatest* backward compatibility (if you don't specify any
-`D` permissions, everything works just as before), while also enabling the new
-semantics at the granularity of a repo, instead of the entire config.
+  * branch deletion is permitted by using `RWD` or `RW+D` -- essentially the
+    current branch permissions with a `D` suffixed
+  * if a repo has a rule containing such a `D`, all `RW+` permissions (for
+    that repo) cease to permit deletion of the ref matched.
+
+This provides the *greatest* backward compatibility, while also enabling the
+new semantics at the granularity of a repo, instead of the entire config.
 
 Note 1: if you find that `RW+` no longer allows deletion but you can't see a
 `D` permission in the rules, remember that gitolite allows a repo config to be
@@ -395,7 +397,7 @@ files.  Be sure to search everywhere :)
 Note 2: a quick way to make this the default for *all* your repos is:
 
     repo @all
-        D   dummy-branch    =   foo
+        RWD     dummy-branch    =   foo
 
 where foo can be either the administrator, or if you can ignore the warning
 message when you push, a non-existant user.

src/gl-compile-conf

@@ -190,7 +190,7 @@ sub parse_conf_file
             s/\bCREAT[EO]R\b/\$creater/g for @repos;
         }
         # actual permission line
-        elsif (/^(-|C|D|R|RW|RW\+) (.* )?= (.+)/)
+        elsif (/^(-|C|R|RW\+?D?) (.* )?= (.+)/)
         {
             my $perms = $1;
             my @refs; @refs = split(' ', $2) if $2;
@@ -261,7 +261,7 @@ sub parse_conf_file
                     # if the user specified even a single 'D' anywhere, make
                     # that fact easy to find; this changes the meaning of RW+
                     # to no longer permit deletes (see update hook)
-                    $repos{$repo}{DELETE_IS_D} = 1 if $perms eq 'D';
+                    $repos{$repo}{DELETE_IS_D} = 1 if $perms =~ /D/;
 
                     # for 2nd level check, store each "ref, perms" pair in order
                     for my $ref (@refs)