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