Contents: what, why, how, decisions / issues

== What? ==

This is a collection of scripts and data which can be used to construct
a metadata preserving git or hg repository of all the zoneinfo releases
since 1986.

== Why? ==

On that note let me say a huge thank you to the combined half a century
of work that Paul and Arthur and everyone else has contributed here.
It is out of respect for the work everyone has done here that I've tried
to create a faithful reproduction of the work you have all given to us.

Last year I read
http://blog.jonudell.net/2009/10/23/a-literary-appreciation-of-the-olsonzoneinfotz-database/
and was hugely impressed by the quiet work we all take for granted.
So hearing about the current issues the maintainers are having I didn't
want the history to be lost.

If you feel the data here is incomplete and you have ideas on additional
information, please contact me so that I may make this archive more
complete.  Thanks.  The easiest way to do this is to issue a pull request
on github.  Alternatively, send me mail at kevin@ie.subric.net.

== How? ==

Instead of using these scripts you can instead get the git or hg
repositories generated by them here:

Git version: https://github.com/lyda/tz
Hg version: https://bitbucket.org/lyda/tz

Note that these are not used by the maintainer - don't send them
pull requests.  And as this set of scripts evolve those repositories
are deleted and recreated so it's a good idea not to pull/fetch from
them either.

For generating the repositories yourself:

* See the */FETCH_DATA files and gather the required data.
* Choose a VCS you want to use.  Currently git or hg are supported.
  Set $VCS to the one you want - i.e. VCS=git
* Go to the work-usenix/ directory and run: ./add.sh "$VCS"
  This will then generate $VCS.settz - a repository that contains all
  known usenet releases.
* Go to the work/ directory.  If you want to copy over the repository
  created in the first step, run: ./cpsettz "$VCS"
* Now run the migration script: ./add "$VCS"
* You will then have a $VCS.tz repository with all changes from 1986 to
  the present (assuming you downloaded the tarballs as described in the
  FETCH_DATA instructions).

== Decisions / Issues ==

These scripts make a number of decisions people could debate.  I have
listed them here so that others could review.

1)  I date each commit based on the date of the message announcing the
    release.  It's possible to extract an arguably more accurate date from
    the files within the repository but since the commit message is based
    on the release message, it was my opinion that date was more correct.

2)  The following files are referred to in the tzarchive (thank you IANA
    for hosting the archive and to GMANE for filling in the blanks).
    I'm pretty sure all of these existed.

      tzcode2002a.tar.gz  tzcode2006e.tar.gz
      tzcode2008e.tar.tz  tzcode2010b.tar.gz  tzcode93g.tar.gz
      tzcode94b.tar.gz    tzcode94c.tar.gz    tzcode94d.tar.gz
      tzcode94e.tar.gz    tzcode94f.tar.gz    tzcode94g.tar.gz
      tzcode94h.tar.gz    tzcode95a.tar.gz    tzcode95b.tar.gz
      tzcode95c.tar.gz    tzcode95f.tar.gz    tzcode96e.tar.gz
      tzcode96f.tar.gz    tzcode96k.tar.gz    tzdata1996m.tar.gz
      tzdata1998f.tar.gz  tzdata1998g.tar.gz  tzdata2002a.tar.gz
      tzdata2006e.tar.gz  tzdata93g.tar.gz    tzdata94a.tar.gz
      tzdata94b.tar.gz    tzdata94d.tar.gz    tzdata94e.tar.gz
      tzdata94f.tar.gz    tzdata94h.tar.gz    tzdata95a.tar.gz
      tzdata95b.tar.gz    tzdata95j.tar.gz    tzdata96f.tar.gz
      tzdata96g.tar.gz

    Notes from reviewing the missing files:

      tzcode94c.tar.gz - can be recreated with
                         <9402101356.AA19044@elsie.nci.nih.gov>
      tzcode94e.tar.gz - might be recreatable w/
                         <9403310434.AA22475@elsie.nci.nih.gov>
      tzcode95a.tar.gz may be bogus
      Possibly missing: betatzcode.tar.gz betatzdata.tar.gz
                        classictzcode.tar.gz classictzdata.tar.gz
                        (they go just before tzcode95a.tar.gz)
      tzcode96k.tar.gz - not bogus but might have been pulled?
                         <9609082035.AA12565@elsie.nci.nih.gov>
                         <9609082115.AA12896@elsie.nci.nih.gov>
      tzdata94a.tar.gz - recreatable with
                         <9402031404.AA26306@elsie.nci.nih.gov>

3)  The tzcode and tzdata files are in the same directory - that's
    how they initially started in 1986.  One could argue that starting
    with releases in 1993 that the code and data should be broken out
    into different directories.

4)  Each commit message has the Message-Id header of the message it
    came from.  That can be used to find the messages and related threads
    in mailing list archives in the future.

5)  For the Usenet files:

      * It's possible there was a release prior to:
        comp.sources.unix/volume4/settz
      * It's possible (likely?) there were releases between:
        comp.sources.unix/volume14/localtime3
        comp.sources.unix/volume18/localtime3

6)  Credits.  All the commits (except the last (currently) by kre)
    are credited to ado.  However in his commit messages he will
    frequently credit others - eggert primarily.  It's possible this
    info is in SCCS but I doubt it.

7)  Since mercurial does not support empty commits, the hg.tz and hg.settz
    created repos have a .hg-migrate.txt file which gives some information
    about each revision in the repository.  For some releases it is the
    only file that changes (obviously the commit text changes as well).

8)  The Usenix archive is not complete.  There's an obvious gap from the
    settz era to the tarballs on elsie.  There might be earlier tarballs;
    there might have been later releases on Usenet.  I have not found any.
    There were discussions about this on mod.sources, comp.sources.unix
    and comp.std.unix.  In addition there were dome related releases on
    comp.sources.unix that I have not included (and might yet):

      volume25/posix-date
      volume26/strftime
      volume26/strftime-2.0
      volume26/strftime-3.0
      volume27/strftime-6.0
      volume28/strftime-6.1
      volume29/strftime-7.0

    In addition there was the volume6/datediffs patch - but it was just
    a diff against the date command on four different unix versions.