contrib/tzdata/CONTRIBUTING

   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@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@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
  87 -----
  88
  89 This file is in the public domain.