Document new source pkg version identifier syntax.

1 files changed, 65 insertions, 21 deletions

diff --git a/specs/source-package-format-2.0.txt b/specs/source-package-format-2.0.txt
index 2b72f90..e5267a7 100644
--- a/specs/source-package-format-2.0.txt
+++ b/specs/source-package-format-2.0.txt
@@ -58,6 +58,9 @@ source package format:
       binary packages.  See section 5 for rationale behind this design.
   * The source package version is no longer included in `control`.
     - It is already given in the most recent entry in `changelog`.
+  * The version identifier syntax now encodes information about source archive
+    repacks and non-trunk distribution uploads.
+    - The syntax has been made strict to make parsing simple and deterministic.
 
 
 5.  Rationale
@@ -177,7 +180,7 @@ children) shall be removed.
 
 All of the following files are located under what is called a "source package
 directory" (`<source-package-directory>` in the tree in section 8).  No naming
-requirements are made for this directory.  See section 20.1 for a recommended
+requirements are made for this directory.  See section 21.1 for a recommended
 naming convention for this directory.
 
 10.1.  `<binpkg>.pkg/`
@@ -195,7 +198,7 @@ This directory contains metadata and scripts for a binary package.
 This file is required.
 
 This file contains control fields describing the binary package.  See section 15
-for the syntax of this file and section 17 for the list of control fields in
+for the syntax of this file and section 19 for the list of control fields in
 this file.
 
 10.3.  `<binpkg>.pkg/install`
@@ -231,7 +234,7 @@ See section 14 for the syntax of this file.
 This file is optional.
 
 This file is a maintainer script to be executed after a binary package is
-unpacked.  See section 19 for more information about maintainer scripts.
+unpacked.  See section 20 for more information about maintainer scripts.
 
 10.6.  `<binpkg>.pkg/postrm`
 ----------------------------
@@ -239,7 +242,7 @@ unpacked.  See section 19 for more information about maintainer scripts.
 This file is optional.
 
 This file is a maintainer script to be executed after a binary package is
-removed.  See section 19 for more information about maintainer scripts.
+removed.  See section 20 for more information about maintainer scripts.
 
 10.7.  `<binpkg>.pkg/preinst`
 ------------------------------
@@ -247,7 +250,7 @@ removed.  See section 19 for more information about maintainer scripts.
 This file is optional.
 
 This file is a maintainer script to be executed before a binary package is
-unpacked.  See section 19 for more information about maintainer scripts.
+unpacked.  See section 20 for more information about maintainer scripts.
 
 10.8.  `<binpkg>.pkg/prerm`
 ------------------------------
@@ -255,7 +258,7 @@ unpacked.  See section 19 for more information about maintainer scripts.
 This file is optional.
 
 This file is a maintainer script to be executed before a binary package is
-removed.  See section 19 for more information about maintainer scripts.
+removed.  See section 20 for more information about maintainer scripts.
 
 10.9.  `build`
 --------------
@@ -371,7 +374,8 @@ format:
 
 `package` is the source package name.
 
-`version` is the source package version number.
+`version` is the source package version.  See section 17 for the syntax of
+source package version identifiers.
 
 `distributions` is a list of distributions into which the package should be
 installed when uploaded to the package archive.  The list consists of one or
@@ -419,7 +423,47 @@ user's filesystem hierarchy.
 TODO
 
 
-17.  Source Package Metadata
+17.  Source Package Version Identifier Syntax
+=============================================
+
+In general, the syntax of source package version identifiers is:
+
+    <pkgver>[+sip<siprev>][-<pkgrev>][+<dist>-<distrev>]
+
+`<pkgver>` is the version of the original upstream package or the native
+package.  It may only consist of lowercase Latin letters, digits, periods, and
+tildes.  It must be at least one character long.  (A regular expression for this
+is `[0-9a-z.~]+`.)
+
+If the upstream source archive needs to be repacked with certain changes for
+compliance with the Software Inclusion Policy, the string `+sip<siprev>` must be
+appended to `<pkgver>`.  `<siprev>` is a number that should be incremented on
+each repack while `<pkgver>` remains constant.  It should be reset to `1` for
+the first repack of a new upstream source archive.  It must be a string of one
+or more digits, the first of which must be greater than or equal to `1`.  (A
+regular expression for this is `[1-9][0-9]*`.)
+
+`<pkgrev>` is the version of the distribution packaging.  It is optional and
+should be omitted for native packages.  It should be incremented on each
+revision of packaging while `<pkgver>` and `<siprev>` remain constant.  It
+should be reset to `1` for the first revision of packaging for a new upstream
+package version or source archive repack.  It must be a string of one or more
+digits, the first of which must be greater than or equal to `1`.  (A regular
+expression for this is `[1-9][0-9]*`.)
+
+If the package is to be installed into a distribution other than `trunk`, the
+string `+<dist>-<distrev>` must be appended to the end of the version
+identifier.  `<dist>` is the distribution into which the package is to be
+installed, may only consist of lowercase Latin letters and digits, and must be
+at least one character long.  (A regular expression for this is `[a-z0-9]+`.)
+`<distrev>` is a number that should be incremented on each upload to `<dist>`
+while `<pkgver>`, `<siprev>`, and `<pkgrev>` remain constant.  It should be
+reset to `1` for the first upload to `<dist>` of a new upstream package version,
+source archive repack, or distribution packaging revision.  It must be a string
+of one or more digits, the first of which must be greater than or equal to `1`.
+(A regular expression for this is `[1-9][0-9]*`.)
+
+18.  Source Package Metadata
 ============================
 
 The fields in the source package metadata are:
@@ -444,7 +488,7 @@ The fields in the source package metadata are:
     by angle brackets or any other characters.
 
 
-18.  Binary Package Metadata
+19.  Binary Package Metadata
 ============================
 
 The fields in the binary package metadata are:
@@ -509,24 +553,24 @@ The fields in the binary package metadata are:
     description.
 
 
-19.  Maintainer Scripts
+20.  Maintainer Scripts
 =======================
 
-19.1.  Maintainer Script Format
+20.1.  Maintainer Script Format
 -------------------------------
 
 TODO
 
-19.2.  Calling Standard
+20.2.  Calling Standard
 -----------------------
 
 TODO
 
 
-20.  Packaging Recommendations
+21.  Packaging Recommendations
 ==============================
 
-20.1.  Source Package Directory Naming
+21.1.  Source Package Directory Naming
 --------------------------------------
 
 It is recommended that the name of the source package directory be simply the
@@ -534,7 +578,7 @@ name of the source package.  Including the package version number or any part
 thereof in the directory name is not recommended, as this number will likely
 change over time.
 
-20.2.  `build` File Generation
+21.2.  `build` File Generation
 ------------------------------
 
 For non-trivial packages, it is recommended that the `config` script generates a
@@ -549,7 +593,7 @@ However, it is not specified by POSIX.1 (and therefore cannot be expected to be
 supported by all implementations).  Furthermore, conditional logic goes beyond
 the original design of the `make` utility.
 
-20.3.  Dynamic Binary Package Generation
+21.3.  Dynamic Binary Package Generation
 ----------------------------------------
 
 For certain source packages, the set of binary packages to be built depends on
@@ -560,15 +604,15 @@ generated by the `config` script from template directories named
 `<binpkg>.pkg.in/` or similar.
 
 
-21.  Example Files
+22.  Example Files
 ==================
 
 In the following sections are some example files that might be used for the
-`opkg` source package.  They observe the recommendation made in section 20.2 to
+`opkg` source package.  They observe the recommendation made in section 21.2 to
 make the `config` script generate a `build` makefile from an input `build.in`
 file.
 
-21.1.  Example `config` File
+22.1.  Example `config` File
 ----------------------------
 
 Following is an example `config` file:
@@ -586,7 +630,7 @@ Following is an example `config` file:
 It detects whether the user intends to cross build the software and generates
 appropriate `build` and `host` options for the software's `configure` script.
 
-21.2.  Example `build.in` File
+22.2.  Example `build.in` File
 ------------------------------
 
 Following is an example `build.in` file:
@@ -638,7 +682,7 @@ Additionally, this file relies on the opkhelper utilities to perform tasks
 related to the production of binary packages.
 
 
-22.  Legal Notice
+23.  Legal Notice
 =================
 
 Copyright (C) 2012 Patrick "P. J." McDermott