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

[Rodney W. Grimes]

> 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).

Diff and patch had issues with them, and still do?

> 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.

Yes, there was some cvs admin and/or rm's done, not exactly repo surgery,
which did occur on other types of repairs, some very poorly.

> > > 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.
This rings a bell.

> > 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.

How do the tools today deal with taking a binary off the vendor branch?
Isn't this still a for-ever night mare merge thing to deal with?

> > > 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.

I agree on location, in or near the committers guide.  It may be
time to expand that to have a procedures section (how to vendor import,
how to MFC, etc), and a guidelines section (commit messages, must/should/
can/shall not etc)

> 
> 
> > > 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.

Agree, and that is probably all the document should say on that subject.

> Warner
-- 
Rod Grimes                                                 rgrimes at freebsd.org