"Fossies" - the Fresh Open Source Software Archive

Member "CONTRIBUTING" (14 Dec 2021, 3252 Bytes) of package /linux/misc/tzcode2022g.tar.gz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "CONTRIBUTING": 2021e_vs_2022e.

    1 # Contributing to the tz code and data
    2 
    3 Please do not create issues or pull requests on GitHub, as the
    4 proper procedure for proposing and distributing patches is via
    5 email as described below.
    6 
    7 The time zone database is by no means authoritative: governments
    8 change timekeeping rules erratically and sometimes with little
    9 warning, the data entries do not cover all of civil time before
   10 1970, and undoubtedly errors remain in the code and data.  Feel
   11 free to fill gaps or fix mistakes, and please email improvements
   12 to <tz@iana.org> for use in the future.  In your email, please give
   13 reliable sources that reviewers can check.
   14 
   15 ## Contributing technical changes
   16 
   17 To 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 
   21 For more-elaborate or possibly-controversial changes,
   22 such 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>.
   25 It is also good to browse the mailing list archives
   26 <https://mm.icann.org/pipermail/tz/> for examples of patches that tend
   27 to work well.  Additions to data should contain commentary citing
   28 reliable sources as justification.  Citations should use "https:" URLs
   29 if available.
   30 
   31 For changes that fix sensitive security-related bugs, please see the
   32 distribution's 'SECURITY' file.
   33 
   34 Please submit changes against either the latest release
   35 <https://www.iana.org/time-zones> or the main branch of the development
   36 repository.  The latter is preferred.
   37 
   38 ## Sample Git workflow for developing contributions
   39 
   40 If 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 
   97 This file is in the public domain.