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. |