From 55ac4f085ecaf7ef0a0c010672fc52717680e6b1 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Fri, 4 Nov 2016 11:26:36 -0700
Subject: [PROPOSED] Document commit tags better
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* NEWS: Document this.  Don’t say “official” when it’s not official.
* Theory (Interface stability):
Point to tz-link.htm for how releases are distributed.
* tz-link.htm (The tz database): Document relationship between
development commit tags and release numbers.  Give shell command
for cloning development repository.
---
 NEWS        |  8 +++++++-
 Theory      | 10 ++++++----
 tz-link.htm | 21 ++++++++++++---------
 3 files changed, 25 insertions(+), 14 deletions(-)

diff --git a/NEWS b/NEWS
index 4eca755..d5f7217 100644
--- a/NEWS
+++ b/NEWS
@@ -15,6 +15,12 @@ Unreleased, experimental changes
     should now work better on systems where the 'link' system call
     does not follow symbolic links.
 
+  Changes to documentation and commentary
+
+    tz-link.htm now documents the relationship between release version
+    numbers and development-repository commit tags.  (Suggested by
+    Paul Koning.)
+
 
 Release 2016i - 2016-11-01 23:19:52 -0700
 
@@ -228,7 +234,7 @@ Release 2016g - 2016-09-13 08:56:38 -0700
     23 commits and some working-file changes have been made since
     release 2016g, the version number is now something like
     '2016g-23-g50556e3-dirty' instead of the misleading '2016g'.
-    Official releases uses the same version number format as before,
+    Tagged releases use the same version number format as before,
     e.g., '2016g'.  To support the more-accurate version number, its
     specification has moved from a line in the Makefile to a new
     source file 'version'.
diff --git a/Theory b/Theory
index 677baf6..07e449b 100644
--- a/Theory
+++ b/Theory
@@ -8,6 +8,7 @@ Theory and pragmatics of the tz code and data
 	Time zone abbreviations
 	Accuracy of the tz database
 	Time and date functions
+	Interface stability
 	Calendrical issues
 	Time and time zones on Mars
 
@@ -601,10 +602,11 @@ The tz code and data supply the following interfaces:
 
  * The format of the country code file, documented in iso3166.tab.
 
-When these interfaces are changed, an effort is made to preserve
-backward compatibility.  For example, tz data files typically do not
-rely on recently-added zic features, so that users can run older zic
-versions to process newer data files.
+Interface changes in a release attempt to preserve compatibility with
+recent releases.  For example, tz data files typically do not rely on
+recently-added zic features, so that users can run older zic versions
+to process newer data files.  The tz-link.htm file describes how
+releases are tagged and distributed.
 
 Interfaces not listed above are less stable.  For example, users
 should not rely on particular UT offsets or abbreviations for time
diff --git a/tz-link.htm b/tz-link.htm
index aec8a1c..46be1ad 100644
--- a/tz-link.htm
+++ b/tz-link.htm
@@ -10,7 +10,7 @@
  content="Sources for time zone and daylight saving time data">
 <meta name="DC.Creator" content="Eggert, Paul">
 <meta name="DC.Contributor" content="Olson, Arthur David">
-<meta name="DC.Date" content="2016-11-01">
+<meta name="DC.Date" content="2016-11-04">
 <meta name="DC.Description"
  content="Sources of information about time zones and daylight saving time">
 <meta name="DC.Identifier"
@@ -120,7 +120,7 @@ gzip -dc tzdata-latest.tar.gz | tar -xf -
 <p>Alternatively, the following shell commands download the same
 release in a single-tarball format containing extra data
 useful for regression testing:</p>
-<pre style="margin-left: 2em"><code>wget --retr-symlinks 'ftp://ftp.iana.org/tz/tzdb-latest.tar.lz'
+<pre style="margin-left: 2em"><code>wget <a href="ftp://ftp.iana.org/tz/tzdb-latest.tar.lz">ftp://ftp.iana.org/tz/tzdb-latest.tar.lz</a>
 <a href="http://www.nongnu.org/lzip/">lzip</a> -dc tzdb-latest.tar.lz | tar -xf -
 </code></pre>
 <p>These commands use convenience links to the latest of the
@@ -139,14 +139,17 @@ through <samp>zzz</samp>, and so on).
 The releases can also be obtained from the
 <a href="http://www.iana.org/time-zones">Time Zone Database website</a>
 of the <a href="http://www.iana.org">Internet Assigned Numbers
-Authority (IANA)</a>.
-A <a href="https://github.com/eggert/tz">development
-repository</a> of the code and data is available
-in <a href="https://git-scm.com">Git</a> form
-from <a href="https://github.com">GitHub</a>; be careful, as this
-repository is less well tested and probably contains more errors.
+Authority (IANA)</a>.</p>
+<p>Alternatively, a development repository of code and data can be
+retrieved from <a href="https://github.com">GitHub</a> via the shell
+command:</p>
+<pre style="margin-left: 2em"><code><a href="https://git-scm.com">git</a> clone <a href="https://github.com/eggert/tz">https://github.com/eggert/tz</a>
+</code></pre>
+<p>Since 2012, each release has been tagged in the development
+repository. Untagged commits are less well tested and probably contain
+more errors.</p>
 <p>
-After extracting a distribution's files, see its
+After obtaining the code and data files, see the
 <code>README</code> file for what to do next.
 The code lets you compile the <code><abbr>tz</abbr></code> source files into
 machine-readable binary files, one for each location. It also lets
-- 
2.7.4