svn commit: r345138 - head/share/man/man9

[Warner Losh]

On Thu, Mar 14, 2019 at 3:43 PM Ed Maste <emaste at freebsd.org> wrote:

> On Thu, 14 Mar 2019 at 14:55, Rodney W. Grimes
> <freebsd at gndrsh.dnsmgr.net> wrote:
> >
> > We should of documented what the decision process and criteria was
> > that lead to the decission to uuencode the files.
>
> Doing some archaeology, the first instance of a uuencoded file I can
> find is r1796, "Got rid of a couple of binary files by uuencoding.  49
> more to go." There's no explanation of why the change was made.
> Evidence suggests that in 1994 it was just accepted as impossible or
> not permitted to have binary files in the tree, but this has not been
> the case for quite some time.
>

CVS had issues with them. sup had issues with them (remember sup?). CTM
originally didn't cope but does now (not sure when that changed).

By the time I joined in 95 or so, it was already part of the oral
tradition. It was all over the mailing lists and just something you were
expected to know. I even have a recollection of people screwing up and
there being CVS repo surgery to remove the binary version and bring forward
only the .uu versions. But that was 20ish years ago, so I'm not certain.


> > Thus we could easily revist that criteria, see how much of it no
> > longer applies, possible add counter criteria, and change this
> > decision, with it documented as to why it changed.
>
> With none of this documented anywhere I'm going to rely on oral
> history from you, phk, or other FreeBSD committers active in the mid
> 90s to provide guidance on what we can revisit and what to check if it
> no longer applies.
>

It no longer applies. svn copes well, git copes well, perforce coped well
(though not too relevant these days).

IIRC, there used to be something about it in the CVS section of one of the
handbook chapters, but all that stuff was removed a long time ago and may
be hard to find today.


> The reason not to do it is uuencoding adds about a 40% space penalty,
> adds to the build time (to uudecode), and makes changes harder to
> review. In my mind dropping the unnecessary uuencoding is similar to
> dropping build-time patching of files in the source tree (another
> workaround we used to have for limitations of our older VCS).
>

Yes. Bringing a file off a vendor branch was generally greeted with much
gnashing of teeth and much bile. And for good reason: the person taking it
off the vendor branch was trivial, but it caused real and lasting conflicts
for every single new import after that. The pain was real, and borne by the
maintainer, not by the taker-off-the-brancher.


> > As is this is just another semi documented project guideline change,
> > I believe there are more than just the firmware files that this
> > change needs noted on.
>
> Yes, we should look at the other cases where we unnecessarily uuencode
> things. I'm not quite sure where we would document high level things
> like this though, do you have a suggestion?  I could see a case for
> somewhat similra topics (e.g. 7-bit ASCII/UTF-8/ISO-8859 guidance)
> fitting into style.9, but I'm not sure this one does.
>

This feels more like committer guide material, not style.9 to me. The
committer guide is showing its age and collection of random detritus that
we need to reorganize and update. This is one of the many issues.


> > We should also note that if they are already in uuencode state
> > to leave them in uuencode state, or do we intened to convert
> > them on next commit, or ???
>
> Good point, converting existing .uu files to binary is just
> unnecessary churn and is not recommended. If someone is going to make
> a change it can be done with the next update.
>

I'd convert them when there's some other reason to handle them. I'm not
swayed by the churn argument, but more because there's little gain here, at
the moment, and it would take someone's time. But if someone takes the
time, I wouldn't stand in the way.

Warner