Principles of development for Inetutils

[Mats Erik Andersson]

Hello all!

I feel compelled to collect in writing some of the principles,
around which my contributions have revolved when it comes to work
on GNU Inetutils. Over time I have become one of the major
contributors to this project, not to say guardian of portability.

I see five cornerstones for this project:

  1. Coding according to GNU standards. This does not include
     conformity with whatever silly viewpoints GCC-developers
     decide to enforce on their products and evaluators.

  2. Observance of the fact that the code base of GNU Inetutils
     is inherited from legacy Berkeley distribution, and that
     a large portion is still in common, albeit with changed
     indenting and white-space, conditioned by the first item above.

  3. GNU Inetutils builds security relevant executables in the
     form of PAM-enabled and Kerberized programs. These must
     under no circumstance be jeopardized by clandestine or
     unnotated changes as introduced by whatever Maverick,
     Daredevil or `tollküner Bursche' might come up with it
     in good faith. Such experiments are best evaluated in
     a local branch before being promoted into `master'.

  4. Related to the second point, portability must remain an end-goal
     as well as mean to an end, offering whomever enduser sensible
     tools that work on differing unices and their varying flavours,
     and ideally produce identical output for the benefit of the
     working systems administrator. The ongoing portability is
     a form of continuous integration not to be dismissed or
     undervalued.

  5. Every commit must be suitably described as a commit message
     and at the same time offer an annotated entry in the file
     ChangeLog describing affected source file and intent.
     There being essentially only one exception, where the commit
     message must add to the first line the text '(silent change)', 
     and as a rule only imports from GNU Lib are meeting this demand,
     as we are not authors of the committed change set.

Let me state immediately: GNU Inetutils is not a GNU/Linux-project.
It is true that our products are not the first of choice for Debian,
but we have an esteemed contributor and collaborator in the DD
Guillem Jover, with whom we do not always agree in detail, but he
is still important to us. In addition, I am myself am an inactive DM
and it is by my work that the support for GNU/kfreebsd got in place
within GNU Inetutils and also some additions for GNU/Hurd.

As to security relevance, let me illustrate the all importance of
documentation by a very recent example. In January this year,
Simon Josefsson picked up and implemented a code change to `telnet'
identified world wide by CVE-2019-0053. In February, I identified
further improvement needed for this matter, and I clearly noted this
in the commit logging and in our ChangeLog. Unfortunately, I made
a mistake in leaving an off-by-one loop hole. Luckily we received
report with suggested patch to remedy this fault. At this point I
got a private email from an Archlinux user expressing concerns as
to when the Archlinux community could expect a release of Inetutils
to resolve this security issue.

Even the thought of neglecting further changes without the mentioning
of CVE-2019-0053 in ChangeLog and in commit log indicates a lack of
understanding security. Telnet is kerberized, so I would as administrator
be wary of projects neglecting this. We already have self-caused problem
in our slow release rate, so please do not jeopardize even further the
little trust we have upheld.

It is a sound rule of thumb to let publicly identified security breaches
be attended by exclusive change sets, as this looks good, upholds
confidence, and works very well with git-blame. (By the way, the use
of git-blame helps a lot in a legacy project like ours.) One exception
to this would be that the same executable or a closely related one
could need similar precautions, like telnet-telnetd.

Other changes are preferably collected together as logical unit in
a single commit, at least as long as they are expression of some
overall kind of thought. The keyword `Likewise' in the ChangeLog
does wonders when describing the change, and even more so at a later
time when someone, even you yourself, happens to revisit more or less
related code. The habit of building towers of one-line changes in
separate commits is a nuisance and is detrimental to code maintenance.

A second recent example is related to portability. In 2019 we received
repeated reports from Zhixiong Chi, that seemed to include some
unexpected behaviour of snprintf(). Once I got around to analyse the
matter -- resulting in `tests/test-snprintf' -- it dawned on me that
only glibc fails to handle the test case offered by Zhixiong, whereas
four BSD variants and Solaris all pass a the relevant test case. Even
more, the replacement code offered by GNU Lib passes the test; only
glibc persists in failing.

When I communicated this to bug-gnulib, Tim Rühsen quickly responded
that the difference is immaterial and is covered by the keyword `restrict'.
GNU Lib has as a result implemented restricted string variables, but
fact remains that the legacy BSD code touched by the report is present
unchanged in todays FreeBSD because it is correct there, but we would
be touched by portability considerations since we target also glibc.
This illustrates once more why proper documentation of change sets are
paramount, putting aside all aspects of personal taste concerning style
for coding.

I believe that my over six hundred entries in ChangeLog have made use
of most variants of annotation practicable. Study them and those entries
of our other authors to develop your own sensitivity for needs and
favours suitable for this community, not forgetting all downstream
users of GNU Inetutils who must understand our changes when they
ponder on the reasons for upgrading their software.

After these hard to digest opinions, let me spread some encouragement.
When I entered this project I had submitted some patch suggestions
to bug-inetutils and as my contributions continued to flow I was
admitted project membership, initially under the provision that I,
until told otherwise, post for acceptance my suggested changes before
performing the commit action into `master'. This was a supportive and
sound measure of training, not to say school, for developing under-
standing of the need to mold ChangeLog as our most vital tool.
I personally value this introduction very much. Trust is not foremost
the ability to do something, but more the insight to know when not to
do something, or to rethink matter further before going into action.

It is probable that this text will stress or break some trust that
I thought I could enjoy, or that I tacitly assumed, but my self-esteem
of what collaborative effort entails, corresponds to the viewpoints
exercised in the above text. I will stoically accept the consequences!

Written with the best of intentions,

  Mats Erik Andersson