/usr/share/doc: some new proposals

[Chris Waters <xtifr@dsp.net>]

Anthony Towns <aj@azure.humbug.org.au> writes:

> [1  <text/plain; us-ascii (7bit)>]
> On Sat, Jul 31, 1999 at 12:40:39AM -0700, Chris Waters wrote:
> > * Stick with /usr/doc until potato is released, then begin a massive
> >   migration, which may or may not involve symlinks.
> >     -  we can't pretend FHS compliance (but we couldn't anyway).
> >     -  some people have already moved and may not want to move back.

>       - requires all changes to be made in a single release cycle
>         (or we're back in the same position we're in at the moment)

No.  Those are both possibilities, but neither is a necessary outcome.

At worst, we'll be in this same position at the *beginning* of a
release cycle, and that alone has one advantage: it increases the
*chance* that we can get a sweeping change done before the next
release.

And, personally, I'd rather focus on changes that *won't* cause
problems for now, like /usr/share/man, /usr/share/info, /var/games,
and things like that, at least with my packages.

> This is the major issue with this option. As fas as I've seen no one's
> been willing to just come out and say "We can to do it", while a number
> have said "We probably can't". *shrug*

It's not a major issue unless you accept the premise that it requires
all changes to be made in a single release cycle, which I don't.  

> Personally, I don't see much difference between this and just leaving
> things be. YMMV, of course.

That's because you're getting ahead of me.  I have a whole *class* of
proposals here.  The thing they all have in common is that they all
involve starting by using /usr/doc in potato.  So, as a class, they
all provide extra time for discussion.  So we don't have to pick one
now *as long as we decide that we will pick one from this class*.

Basically, there are several variables here.  When do we allow
/usr/share/doc?  When do we require it?  Do we allow symlinks?  When
do we allow symlinks?  Do we require them?  When do we require them?
Fortunately, many of these variables are dependent, so we don't have a
true combinatorial explosion on our hands.  :-)

Here's the proposal I think you have in mind: 

DELAYED DO-NOTHING (the Bad One)

  * Until Freeze: uploads must use /usr/doc
  * During Freeze: 1) use /usr/doc for frozen, /usr/share/doc for
                      unstable, *or*
                   2) just use /usr/doc
  * After Release: use /usr/share/doc
  
  + unlike a pure Do-Nothing strategy, users won't hate Potato.
  - still almost as bad as pure Do-Nothing.
  - could make Woody worse.

Now, let's look at a couple of other more likely proposals.

FEW-SYMLINKS (my preference)

  * Until Freeze: stick with /usr/doc (symlinks optional?)
  * During Freeze: symlinks optional, unstable-only packages may
      follow the next rule.
  * After Release: symlinks optional, otherwise, use /usr/share/doc.
  * Before Next Freeze: decide whether it's better to finish adding
      the symlinks or start removing them.

  + If we do it right, we get a fairly quick, but fairly smooth, and
      not-too-painful transition, with a probable minimum of symlinks
      in our stable releases.
  - We may experience schedule slippage if we blow it badly (but that
      could happen anyway).
  = Or we may just end up no worse off.

("Symlinks optional" should maybe be "symlinks recommended" if your
package has lots of interesting stuff in /usr/doc.  But it should be
up to the developer to decide if the tradeoffs are worth it, and when.)

SOME-SYMLINKS 

  * Until Release: symlinks optional 
  * After Release: make symlinks required until it seems like we have
      the problem under control, then start allowing packages to use
      /usr/share/doc only.  (This may or not happen before the _next_
      freeze.)

  + less chance of schedule slippage than last proposal.
  - less chance of a Big Win; more chance we'll end up no better off.

I think all three of these proposals are better than a pure do-nothing
strategy.  I think latter two proposals (as well as some other
possible variants) are *much* better -- they not only give us a
cleaner Potato, but, by starting the ugly part of the process at the
*beginning* of the release cycle, give us a *good shot* at a cleaner
Woody release as well.  It'll be a little more rough on those riding
the unstable train, but that's the price of admission.
-- 
Chris Waters   xtifr@dsp.net | I have a truly elegant proof of the
      or    xtifr@debian.org | above, but it is too long to fit into
http://www.dsp.net/xtifr     | this .signature file.