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://lists.iana.org/hyperkitty/list/tz@iana.org/> 27for examples of patches that tend to work well. 28Changes should contain commentary citing reliable sources. 29Citations should use "https:" URLs if 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 locally, e.g.: 67 68 make TOPDIR=$PWD/tz clean check install 69 ./zdump -v America/Los_Angeles 70 71 Although builds assume only basic POSIX, they use extra features 72 if available. 'make check' accesses validator.w3.org unless you 73 lack 'curl' or use 'make CURL=:'. If you have the latest GCC, 74 "make CFLAGS='$(GCC_DEBUG_FLAGS)'" does extra checking. 75 76 * For each separable change, commit it in the new branch, e.g.: 77 78 git add northamerica 79 git commit 80 81 See recent 'git log' output for the commit-message style. 82 83 * Create patch files 0001-..., 0002-..., ... 84 85 git format-patch main 86 87 * After reviewing the patch files, send the patches to <tz@iana.org> 88 for others to review. 89 90 git send-email main 91 92 For an archived example of such an email, see 93 "[PROPOSED] Fix off-by-1 error for Jamaica and T&C before 1913" 94 <https://mm.icann.org/pipermail/tz/2018-February/026122.html>. 95 96 * Start anew by getting current with the main branch again 97 (the second step above). 98 99----- 100 101This file is in the public domain. 102