Home | History | Annotate | Line # | Download | only in time
CONTRIBUTING revision 1.4 
      1 Contributing to the tz code and data
      2 
      3 The time zone database is by no means authoritative: governments
      4 change timekeeping rules erratically and sometimes with little
      5 warning, the data entries do not cover all of civil time before
      6 1970, and undoubtedly errors remain in the code and data.  Feel
      7 free to fill gaps or fix mistakes, and please email improvements
      8 to tz (a] iana.org for use in the future.  In your email, please give
      9 reliable sources that reviewers can check.
     10 
     11 -----
     12 
     13 Developers can contribute technical changes to the source code and
     14 data as follows.
     15 
     16 To email small changes, please run a POSIX shell command like
     17 'diff -u old/europe new/europe >myfix.patch', and attach
     18 myfix.patch to the email.
     19 
     20 For more-elaborate changes, please read the theory.html file and browse
     21 the mailing list archives <https://mm.icann.org/pipermail/tz/> for
     22 examples of patches that tend to work well.  Additions to
     23 data should contain commentary citing reliable sources as
     24 justification.  Citations should use https: URLs if available.
     25 
     26 Please submit changes against either the latest release in
     27 <https://www.iana.org/time-zones> or the master branch of the development
     28 repository.  The latter is preferred.  If you use Git the following
     29 workflow may be helpful:
     30 
     31   * Copy the development repository.
     32 
     33       git clone https://github.com/eggert/tz.git
     34       cd tz
     35 
     36   * Get current with the master branch.
     37 
     38       git checkout master
     39       git pull
     40 
     41   * Switch to a new branch for the changes.  Choose a different
     42     branch name for each change set.
     43 
     44       git checkout -b mybranch
     45 
     46   * Sleuth by using 'git blame'.  For example, when fixing data for
     47     Africa/Sao_Tome, if the command 'git blame africa' outputs a line
     48     '2951fa3b (Paul Eggert 2018-01-08 09:03:13 -0800 1068) Zone
     49     Africa/Sao_Tome 0:26:56 - LMT 1884', commit 2951fa3b should
     50     provide some justification for the 'Zone Africa/Sao_Tome' line.
     51 
     52   * Edit source files.  Include commentary that justifies the
     53     changes by citing reliable sources.
     54 
     55   * Debug the changes, e.g.:
     56 
     57       make check
     58       make install
     59       ./zdump -v America/Los_Angeles
     60 
     61   * For each separable change, commit it in the new branch, e.g.:
     62 
     63       git add northamerica
     64       git commit
     65 
     66     See recent 'git log' output for the commit-message style.
     67 
     68   * Create patch files 0001-*, 0002-*, ...
     69 
     70       git format-patch master
     71 
     72   * After reviewing the patch files, send the patches to tz (a] iana.org
     73     for others to review.
     74 
     75       git send-email master
     76 
     77     For an archived example of such an email, see
     78     <https://mm.icann.org/pipermail/tz/2018-February/026122.html>.
     79 
     80   * Start anew by getting current with the master branch again
     81     (the second step above).
     82 
     83 Please do not create issues or pull requests on GitHub, as the
     84 proper procedure for proposing and distributing patches is via
     85 email as illustrated above.
     86