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