[BACK]Return to CONTRIBUTING CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libc / time

File: [cvs.NetBSD.org] / src / lib / libc / time / CONTRIBUTING (download)

Revision 1.5, Fri Oct 19 23:05:35 2018 UTC (2 years, 1 month ago) by christos
Branch: MAIN
CVS Tags: phil-wifi-20200421, phil-wifi-20200411, phil-wifi-20200406, phil-wifi-20191119, phil-wifi-20190609, pgoyette-compat-20190127, pgoyette-compat-20190118, pgoyette-compat-1226, pgoyette-compat-1126, pgoyette-compat-1020, netbsd-9-base, netbsd-9-1-RELEASE, netbsd-9-0-RELEASE, netbsd-9-0-RC2, netbsd-9-0-RC1, netbsd-9, is-mlppp-base, is-mlppp, HEAD
Changes since 1.4: +8 -5 lines

Update to 2018f:

  Changes to code

    zic now always generates TZif files where time type 0 is used for
    timestamps before the first transition.  This simplifies the
    reading of TZif files and should not affect behavior of existing
    TZif readers because the same set of time types is used; only
    their internal indexes may have changed.  This affects only the
    legacy zones EST5EDT, CST6CDT, MST7MDT, PST8PDT, CET, MET, and
    EET, which previously used nonzero types for these timestamps.

    Because of the type 0 change, zic no longer outputs a dummy
    transition at time -2**59 (before the Big Bang), as clients should
    no longer need this to handle historical timestamps correctly.
    This reverts a change introduced in 2013d and shrinks most TZif
    files by a few bytes.

    zic now supports negative time-of-day in Rule and Leap lines, e.g.,
    "Rule X min max - Apr lastSun -6:00 1:00 -" means the transition
    occurs at 18:00 on the Saturday before the last Sunday in April.
    This behavior was documented in 2018a but the code did not
    entirely match the documentation.

    localtime.c no longer requires at least one time type in TZif
    files that lack transitions or have a POSIX-style TZ string.  This
    future-proofs the code against possible future extensions to the
    format that would allow TZif files with POSIX-style TZ strings and
    without transitions or time types.

    A read-access subscript error in localtime.c has been fixed.
    It could occur only in TZif files with timecnt == 0, something that
    does not happen in practice now but could happen in future versions.

    localtime.c no longer ignores TZif POSIX-style TZ strings that
    specify only standard time.  Instead, these TZ strings now
    override the default time type for timestamps after the last
    transition (or for all time stamps if there are no transitions),
    just as DST strings specifying DST have always done.

    leapseconds.awk now outputs "#updated" and "#expires" comments,
    and supports leap seconds at the ends of months other than June
    and December.  (Inspired by suggestions from Chris Woodbury.)

  Changes to documentation

    New restrictions: A Rule name must start with a character that
    is neither an ASCII digit nor "-" nor "+", and an unquoted name
    should not use characters in the set "!$%&'()*,/:;<=>?@[\]^`{|}~".
    The latter restriction makes room for future extensions (a
    possibility noted by Tom Lane).

    tzfile.5 now documents what time types apply before the first and
    after the last transition, if any.

    Documentation now uses the spelling "timezone" for a TZ setting
    that determines timestamp history, and "time zone" for a
    geographic region currently sharing the same standard time.

    The name "TZif" is now used for the tz binary data format.

    tz-link.htm now mentions the A0 TimeZone Migration utilities.
    (Thanks to Aldrin Martoq for the link.)

Contributing to the tz code and data

The time zone database is by no means authoritative: governments
change timekeeping rules erratically and sometimes with little
warning, the data entries do not cover all of civil time before
1970, and undoubtedly errors remain in the code and data.  Feel
free to fill gaps or fix mistakes, and please email improvements
to tz@iana.org for use in the future.  In your email, please give
reliable sources that reviewers can check.


Developers can contribute technical changes to the source code and
data as follows.

To email small changes, please run a POSIX shell command like
'diff -u old/europe new/europe >myfix.patch', and attach
myfix.patch to the email.

For more-elaborate or possibly-controversial changes,
such as renaming, adding or removing zones, please read
<https://www.iana.org/time-zones/repository/theory.html> or the file
theory.html.  It is also good to browse the mailing list archives
<https://mm.icann.org/pipermail/tz/> for examples of patches that tend
to work well.  Additions to data should contain commentary citing
reliable sources as justification.  Citations should use https: URLs
if available.

Please submit changes against either the latest release in
<https://www.iana.org/time-zones> or the master branch of the development
repository.  The latter is preferred.  If you use Git the following
workflow may be helpful:

  * Copy the development repository.

      git clone https://github.com/eggert/tz.git
      cd tz

  * Get current with the master branch.

      git checkout master
      git pull

  * Switch to a new branch for the changes.  Choose a different
    branch name for each change set.

      git checkout -b mybranch

  * Sleuth by using 'git blame'.  For example, when fixing data for
    Africa/Sao_Tome, if the command 'git blame africa' outputs a line
    '2951fa3b (Paul Eggert 2018-01-08 09:03:13 -0800 1068) Zone
    Africa/Sao_Tome 0:26:56 - LMT 1884', commit 2951fa3b should
    provide some justification for the 'Zone Africa/Sao_Tome' line.

  * Edit source files.  Include commentary that justifies the
    changes by citing reliable sources.

  * Debug the changes, e.g.:

      make check
      make install
      ./zdump -v America/Los_Angeles

  * For each separable change, commit it in the new branch, e.g.:

      git add northamerica
      git commit

    See recent 'git log' output for the commit-message style.

  * Create patch files 0001-*, 0002-*, ...

      git format-patch master

  * After reviewing the patch files, send the patches to tz@iana.org
    for others to review.

      git send-email master

    For an archived example of such an email, see

  * Start anew by getting current with the master branch again
    (the second step above).

Please do not create issues or pull requests on GitHub, as the
proper procedure for proposing and distributing patches is via
email as illustrated above.