r332 - /web/deps/dep14.mdwn

[hertzog at users.alioth.debian.org]

Author: hertzog
Date: Thu Nov 10 13:58:51 2016
New Revision: 332

URL: http://svn.debian.org/wsvn/dep/?sc=1&rev=332
Log:
DEP-14: Version -> refname mangling: Escape dots

Patch by Ian Jackson following debian-devel discussion:
https://lists.debian.org/20161103174816.6hrvmrbpapao7l53@pitfall

Modified:
    web/deps/dep14.mdwn

Modified: web/deps/dep14.mdwn
URL: http://svn.debian.org/wsvn/dep/web/deps/dep14.mdwn?rev=332&op=diff
==============================================================================
--- web/deps/dep14.mdwn	(original)
+++ web/deps/dep14.mdwn	Thu Nov 10 13:58:51 2016
@@ -3,7 +3,7 @@
     Title: Recommended layout for Git packaging repositories
     DEP: 14
     State: DRAFT
-    Date: 2014-11-04
+    Date: 2016-11-09
     Drivers: Raphael Hertzog <hertzog at debian.org>
     URL: http://dep.debian.net/deps/dep14
     Source: http://anonscm.debian.org/viewvc/dep/web/deps/dep14.mdwn
@@ -60,8 +60,26 @@
 
 When a Git tag needs to refer to a specific version of a Debian package,
 the Debian version needs to be mangled to cope with Git's restrictions.
-The colon (`:`) needs to be replaced with a percent (`%`), and the tilde
-(`~`) needs to be replaced with an underscore (`_`).
+This mangling is deterministic and reversible:
+
+ * Each colon (`:`) is replaced with a percent (`%`)
+ * Each tilde (`~`) is replaced with an underscore (`_`)
+ * A hash (`#`) is inserted between each pair of adjacent dots (`..`)
+ * A hash (`#`) is appended if the last character is a dot (`.`)
+ * If the version ends in precisely `.lock`
+   (dot `l` `o` `c` `k`, lowercase, at the end of the version),
+   a hash (`#`) is inserted after the dot, giving `.#lock`.
+
+This can be expressed concisely in the following Perl5 statements:
+
+     y/:~/%_/;
+     s/\.(?=\.|$|lock$)/.#/g;
+
+The reverse transformation is:
+
+ * Each percent (`%`) is replaced with a colon (`:`)
+ * Each underscore (`_`) is replaced with a tilde (`~`)
+ * Each hash (`#`) is deleted
 
 Packaging branches and tags
 ===========================
@@ -274,3 +292,4 @@
 =======
 
 * 2014-11-05: Initial draft by Raphaël Hertzog.
+* 2016-11-09: Extended version mangling to troublesome dots -- Ian Jackson.