CONTRIBUTING revision 1.6
190075SobrienContributing to the tz code and data 2169689Skan 3132718SkanThe time zone database is by no means authoritative: governments 490075Sobrienchange timekeeping rules erratically and sometimes with little 590075Sobrienwarning, the data entries do not cover all of civil time before 6132718Skan1970, and undoubtedly errors remain in the code and data. Feel 790075Sobrienfree to fill gaps or fix mistakes, and please email improvements 8132718Skanto tz@iana.org for use in the future. In your email, please give 9132718Skanreliable sources that reviewers can check. 10132718Skan 11132718Skan----- 1290075Sobrien 13132718SkanDevelopers can contribute technical changes to the source code and 14132718Skandata as follows. 15132718Skan 16132718SkanTo email small changes, please run a POSIX shell command like 1790075Sobrien'diff -u old/europe new/europe >myfix.patch', and attach 18132718Skanmyfix.patch to the email. 19132718Skan 20169689SkanFor more-elaborate or possibly-controversial changes, 21169689Skansuch as renaming, adding or removing zones, please read 2290075Sobrien<https://www.iana.org/time-zones/repository/theory.html> or the file 2390075Sobrientheory.html. It is also good to browse the mailing list archives 2490075Sobrien<https://mm.icann.org/pipermail/tz/> for examples of patches that tend 2590075Sobriento work well. Additions to data should contain commentary citing 2690075Sobrienreliable sources as justification. Citations should use https: URLs 2790075Sobrienif available. 2890075Sobrien 2990075SobrienFor changes that fix sensitive security-related bugs, please see the 3090075Sobrienfile SECURITY. 31169689Skan 3290075SobrienPlease submit changes against either the latest release in 33169689Skan<https://www.iana.org/time-zones> or the main branch of the development 3490075Sobrienrepository. The latter is preferred. If you use Git the following 3590075Sobrienworkflow may be helpful: 3690075Sobrien 3790075Sobrien * Copy the development repository. 3890075Sobrien 3990075Sobrien git clone https://github.com/eggert/tz.git 4090075Sobrien cd tz 4190075Sobrien 4290075Sobrien * Get current with the main branch. 4390075Sobrien 4490075Sobrien git checkout main 4590075Sobrien git pull 46132718Skan 4790075Sobrien * Switch to a new branch for the changes. Choose a different 4890075Sobrien branch name for each change set. 4990075Sobrien 5090075Sobrien git checkout -b mybranch 51117395Skan 5290075Sobrien * Sleuth by using 'git blame'. For example, when fixing data for 5390075Sobrien Africa/Sao_Tome, if the command 'git blame africa' outputs a line 5490075Sobrien '2951fa3b (Paul Eggert 2018-01-08 09:03:13 -0800 1068) Zone 5590075Sobrien Africa/Sao_Tome 0:26:56 - LMT 1884', commit 2951fa3b should 5690075Sobrien provide some justification for the 'Zone Africa/Sao_Tome' line. 5790075Sobrien 5890075Sobrien * Edit source files. Include commentary that justifies the 5990075Sobrien changes by citing reliable sources. 6090075Sobrien 61169689Skan * Debug the changes, e.g.: 6290075Sobrien 63169689Skan make check 6490075Sobrien make install 6590075Sobrien ./zdump -v America/Los_Angeles 6690075Sobrien 6790075Sobrien * For each separable change, commit it in the new branch, e.g.: 6890075Sobrien 69132718Skan git add northamerica 7090075Sobrien git commit 7190075Sobrien 7290075Sobrien See recent 'git log' output for the commit-message style. 7390075Sobrien 7490075Sobrien * Create patch files 0001-*, 0002-*, ... 7590075Sobrien 7690075Sobrien git format-patch main 7790075Sobrien 78169689Skan * After reviewing the patch files, send the patches to tz@iana.org 7990075Sobrien for others to review. 80169689Skan 8190075Sobrien git send-email main 8290075Sobrien 8390075Sobrien For an archived example of such an email, see 84132718Skan <https://mm.icann.org/pipermail/tz/2018-February/026122.html>. 8590075Sobrien 8690075Sobrien * Start anew by getting current with the main branch again 8790075Sobrien (the second step above). 8890075Sobrien 8990075SobrienPlease do not create issues or pull requests on GitHub, as the 9090075Sobrienproper procedure for proposing and distributing patches is via 9190075Sobrienemail as illustrated above. 92169689Skan