[Git][NTPsec/ntpsec][20L-Dec24-unholy] Update some docs to reflect post 1.2.0 changes.

James Browning gitlab at mg.gitlab.com
Tue Dec 29 12:56:37 UTC 2020 


James Browning pushed to branch 20L-Dec24-unholy at NTPsec / ntpsec


Commits:
77c7b3f6 by James Browning at 2020-12-29T04:55:27-08:00
Update some docs to reflect post 1.2.0 changes.

- - - - -


3 changed files:

- NEWS.adoc
- devel/hacking.adoc
- packaging/packaging.adoc


Changes:

=====================================
NEWS.adoc
=====================================
@@ -12,6 +12,19 @@ on user-visible changes.
 
 == Repository Head ==
 
+Remove --build-epoch and replace it with arbitrary --build-desc text.
+fix pivot of 2020 Jan 01. Passing '--build-desc=$(date -u
++%Y-%m-%dT%H:%M:%Sz)' restores the previous default extended version.
+
+Compare versions of ntp.ntpc and libntpc printing a warning is
+mismatched. Fix libntpc install path if using it.
+
+Reduce maxclocks to 5 to reduce the NTP pool load.
+
+print LIBDIR during ./waf configure.
+
+Documentation, new GPG key, and miscellaneous cleanups.
+
 == 2020-10-06: 1.2.0 ==
 
 The minor version bump is to indicate official official support of
@@ -22,7 +35,7 @@ On this day in 1783, Benjamin Hanks received a patent for a
 self-winding clock he planned to install in the Old Dutch Church in
 Kingston, New York, supposedly making it the first public clock in
 what became the New York City metropolitan area.
- 
+
 NTS-KE client now defaults to port 4460.
 
 NTS-KE server now listens on port 4460.


=====================================
devel/hacking.adoc
=====================================
@@ -497,17 +497,13 @@ C was the minor.  They also use release-candidate suffixes.
 
 == Version string
 
-We use the BUILD_EPOCH as described in packaging/packaging.adoc for
-the timestamp (converted to RFC 3339 format) part of the version
-string reported in ntpd and other binaries.
-
 Release builds have version strings of the form:
 
-<base version number> <BUILD_EPOCH in RFC 3339 format>
+<base version number><trim()d --build-desc with a prepended space>
 
 Development builds have version strings of the form:
 
-<base version number>+ <BUILD_EPOCH in RFC 3339 format> (git rev <git shorthash>)
+<base version number>+<commits since last tag>-g<git short hash><conditional '-dirty'> <trim()d --build-desc with a prepended space>
 
 == Contribution workflow and conventions
 
@@ -812,6 +808,6 @@ cat > ~/.gitconfig
 ^D
 -------------------------------------------------------------
 
-. 
+.
 
 //end


=====================================
packaging/packaging.adoc
=====================================
@@ -18,9 +18,9 @@ pool group of its own. This may change in the future.
 
 Many tools (actually, almost everything except the core daemon itself)
 have been moved from C to Python. This is an important step for
-improving maintainability and reducing attack surface.  However, we
-know that some platforms cannot support Python or choose not to
-include it in their core configuration.
+improving maintainability and reducing the attack surface.  However,
+we know that some platforms cannot support Python or choose not
+to include it in their core configuration.
 
 For these platforms, we recommend using cx_Freeze to render the NTPsec
 Python programs, and all their imported modules, into standalone files.
@@ -35,7 +35,7 @@ can install it with pip like this:
 
 ```
 pip install cx_Freeze
-````
+```
 
 You may find that you also need to install the package 'patchelf'.
 
@@ -58,54 +58,43 @@ binaries created by cx_freeze.
 
 == Hacking Python shebangs
 
-The shebang lines in our Python scripts point to "python".  Part of
-our standard tests check that you can change that to "python3" without
-breaking anything.
-
-We are aware that the Python 3 transition is well advanced.  We are
-also aware that PEP394 strongly urges all distributors to point
-'python' at Python 2.
+The shebang lines in our Python scripts point to the value of
+--pyshebang (default "python"). Part of our standard development tests
+check that you can change that to "python3" without breaking anything.
 
-This leaves us with a choice to either (a) change the shebangs to
-python3 ourselves, causing breakage to users stuck with Python 2
-and installing from source, or (b) not change them, leaving it up
-to distro maintainers to hack them in whatever way is appropriate for
-their distro's Python policy.
-
-We think the choice that minimizes overall pain, and directs it to
-the party best able to cope, is clear.  We choose (b).
+We are aware that the Python 3 transition is well advanced.  We are also
+aware that PEP394 strongly urges all distributors to point 'python' at
+Python 2.
 
 == Cross-era interoperability in modular calendar arithmetic
 
-The protocol necessarily uses time/date stamps of finite length in
-order to fit into fixed-size fields; they happen to have a 136-year
-cycle, but the problems this produces aren't dependent on the specific
-cycle length.  Thus, each instance of ntpd speaks time based on a
-specific epoch (cycle start date).  The epoch of era 0 was at the
-beginning of 1900; the epoch of era 1 will be in 2036.
+The protocol necessarily uses time/date stamps of finite length
+to fit into fixed-size fields; they happen to have a 136-year cycle, but
+the problems this produces aren't dependent on the specific cycle
+length.  Thus, each instance of ntpd speaks time based on a specific
+epoch (cycle start date).  The epoch of era 0 was at the beginning of
+1900; the epoch of era 1 will be in 2036.
 
 Two instances talking to each other have no way to know that they're
-based in the same era. To mitigate this problem, each instance
-has a pivot date and resolves incoming timestamps to the era that
-minimizes distance between now and the timestamp.  This procedure
-is part of the core protocol specification.
-
-An instance's pivot time is constructed from BUILD_EPOCH defined at
-configure time in config.h.  If BUILD_EPOCH is set to a known time
-then the binaries are reproducible.  By default the BUILD_EPOCH is the
-time when the last './waf configure' was run.  You can override the
-BUILD_EPOCH with './waf configure --build-epoch' or using the SOURCE_DATE_EPOCH
-environment variable.
+based in the same era. To mitigate this problem, each instance has a
+pivot date and resolves incoming timestamps to the era that minimizes
+the distance between now and the timestamp.  This procedure is part of the
+core protocol specification.
+
+An instance's pivot time is constructed from a hardcoded UNIX second
+count in the source code. This is also used to disambiguate the current
+GPS era. This number should be updated every nine years or so (approx
+512w). This should make the binaries reproducible.
 
 More information on reproducible builds is at:
 https://reproducible-builds.org/[https://reproducible-builds.org/]
 
 == Disambiguation of NMEA dates
 
-Due to bad design of NMEA0183, the reporting protocol used by many GPS
-sensors, the NMEA driver in NTPsec sometimes has to make an assumption
-about what century it is.  Choice of a base-century hits the same
-issues; so here the year derived from the BUILD_EPOCH is also used.  The
+Due to the bad design of NMEA0183, the reporting protocol used by many GPS
+sensors, the NMEA driver in NTPsec sometimes has to assume
+what century it is.  Choice of a base-century hits the same
+issues, so here the year derived from a hardcoded UNIX second count. The
 alternative - trusting the system clock to report the right century -
 could produce very bad behavior near century boundaries, and also on
 cold-start of systems without an RTC.



View it on GitLab: https://gitlab.com/NTPsec/ntpsec/-/commit/77c7b3f6cf07cb385de7fcd3e621dd9e1c36a257

-- 
View it on GitLab: https://gitlab.com/NTPsec/ntpsec/-/commit/77c7b3f6cf07cb385de7fcd3e621dd9e1c36a257
You're receiving this email because of your account on gitlab.com.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ntpsec.org/pipermail/vc/attachments/20201229/c99c1216/attachment-0001.htm>

More information about the vc mailing list