Home | History | Annotate | Line # | Download | only in time
CONTRIBUTING revision 1.6 
      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 or possibly-controversial changes,
     21 such as renaming, adding or removing zones, please read
     22 <https://www.iana.org/time-zones/repository/theory.html> or the file
     23 theory.html.  It is also good to browse the mailing list archives
     24 <https://mm.icann.org/pipermail/tz/> for examples of patches that tend
     25 to work well.  Additions to data should contain commentary citing
     26 reliable sources as justification.  Citations should use https: URLs
     27 if available.
     28 
     29 For changes that fix sensitive security-related bugs, please see the
     30 file SECURITY.
     31 
     32 Please submit changes against either the latest release in
     33 <https://www.iana.org/time-zones> or the main branch of the development
     34 repository.  The latter is preferred.  If you use Git the following
     35 workflow may be helpful:
     36 
     37   * Copy the development repository.
     38 
     39       git clone https://github.com/eggert/tz.git
     40       cd tz
     41 
     42   * Get current with the main branch.
     43 
     44       git checkout main
     45       git pull
     46 
     47   * Switch to a new branch for the changes.  Choose a different
     48     branch name for each change set.
     49 
     50       git checkout -b mybranch
     51 
     52   * Sleuth by using 'git blame'.  For example, when fixing data for
     53     Africa/Sao_Tome, if the command 'git blame africa' outputs a line
     54     '2951fa3b (Paul Eggert 2018-01-08 09:03:13 -0800 1068) Zone
     55     Africa/Sao_Tome 0:26:56 - LMT 1884', commit 2951fa3b should
     56     provide some justification for the 'Zone Africa/Sao_Tome' line.
     57 
     58   * Edit source files.  Include commentary that justifies the
     59     changes by citing reliable sources.
     60 
     61   * Debug the changes, e.g.:
     62 
     63       make check
     64       make install
     65       ./zdump -v America/Los_Angeles
     66 
     67   * For each separable change, commit it in the new branch, e.g.:
     68 
     69       git add northamerica
     70       git commit
     71 
     72     See recent 'git log' output for the commit-message style.
     73 
     74   * Create patch files 0001-*, 0002-*, ...
     75 
     76       git format-patch main
     77 
     78   * After reviewing the patch files, send the patches to tz (a] iana.org
     79     for others to review.
     80 
     81       git send-email main
     82 
     83     For an archived example of such an email, see
     84     <https://mm.icann.org/pipermail/tz/2018-February/026122.html>.
     85 
     86   * Start anew by getting current with the main branch again
     87     (the second step above).
     88 
     89 Please do not create issues or pull requests on GitHub, as the
     90 proper procedure for proposing and distributing patches is via
     91 email as illustrated above.
     92