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.  The mailing list and its
14archives are public, so please do not send confidential information.
15
16## Contributing technical changes
17
18To email small changes, please run a POSIX shell command like
19‘diff -u old/europe new/europe >myfix.patch’, and attach
20‘myfix.patch’ to the email.
21
22For more-elaborate or possibly controversial changes,
23such as renaming, adding or removing zones, please read
24“Theory and pragmatics of the tz code and data”
25<https://www.iana.org/time-zones/repository/theory.html>.
26It is also good to browse the mailing list archives
27<https://lists.iana.org/hyperkitty/list/tz@iana.org/>
28for examples of patches that tend to work well.
29Changes should contain commentary citing reliable sources.
30Citations should use ‘https:’ URLs if available.
31
32For changes that fix sensitive security-related bugs, please see the
33distribution’s SECURITY file.
34
35Please submit changes against either the latest release
36<https://www.iana.org/time-zones> or the main branch of the development
37repository.  The latter is preferred.
38
39## Sample Git workflow for developing contributions
40
41If you use Git the following workflow may be helpful:
42
43  * Copy the development repository.
44
45        git clone https://github.com/eggert/tz.git
46        cd tz
47
48  * Get current with the main branch.
49
50        git checkout main
51        git pull
52
53  * Switch to a new branch for the changes.  Choose a different
54    branch name for each change set.
55
56        git checkout -b mybranch
57
58  * Sleuth by using ‘git blame’.  For example, when fixing data for
59    Africa/Sao_Tome, if the command ‘git blame africa’ outputs a line
60    ‘2951fa3b (Paul Eggert 2018-01-08 09:03:13 -0800 1068) Zone
61    Africa/Sao_Tome 0:26:56 - LMT 1884’, commit 2951fa3b should
62    provide some justification for the ‘Zone Africa/Sao_Tome’ line.
63
64  * Edit source files.  Include commentary that justifies the
65    changes by citing reliable sources.
66
67  * Debug the changes locally, e.g.:
68
69        make TOPDIR=$PWD/tz clean check install
70        ./zdump -v America/Los_Angeles
71
72    Although builds assume only basic POSIX, they use extra features
73    if available.  ‘make check’ accesses validator.w3.org unless you
74    lack ‘curl’ or use ‘make CURL=:’.  If you have the latest GCC,
75    ‘make CFLAGS='$(GCC_DEBUG_FLAGS)'’ does extra checking.
76
77  * For each separable change, commit it in the new branch, e.g.:
78
79        git add northamerica
80        git commit
81
82    See recent ‘git log’ output for the commit-message style.
83
84  * Create patch files 0001-..., 0002-..., ...
85
86        git format-patch main
87
88  * Check that the patch files and your email setup contain only
89    information that you want to make public.
90
91  * After reviewing the patch files, send the patches to <tz@iana.org>
92    for others to review.
93
94        git send-email main
95
96    For an archived example of such an email, see
97    “[PROPOSED] Fix off-by-1 error for Jamaica and T&C before 1913”
98    <https://mm.icann.org/pipermail/tz/2018-February/026122.html>.
99
100  * Start anew by getting current with the main branch again
101    (the second step above).
102
103-----
104
105This file is in the public domain.
106