[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

/usr/doc transition and other things

Hello world,

By chance I discovered Klee's debian-ctte list archive on master [0]. By
luck, it was world readable so I snarfed a copy. I'm shocked and amazed
to find that the -ctte actually has done stuff. And pleased.

So first, my congratulations to Raul on his acclamation as techinical
committee chair. I'm sure you'll do a good job.

Secondly, I'd like to agree with one of Raul's major points in his first
message in the "/usr/doc issue" thread). In essence:

	The -policy group shouldn't change policy to declare that all
	packages are buggy. (and hence the FHS policy change was badly

Unfortunately, Klee's archives stop at about this point, so I'm not sure
if anything much further's been said about it.

Anyway, as I said, I think this is a good idea. It forces policy to
consider the transition (you can't just say "all these packages suck, fix
them", you have to find some way of making the new and the old packages
work together). This means we *have* to make the transition work, which
improves partial upgrades, and gives us an easy out if we don't happen
to get all the packages transitioned by the time we decide to release.

I'm probably making to grandiose a claim here, but I think this is the
proper way of handling the difference of opinion between Chris (and kin)
and Manoj (and kith) about mentioning releases by names and doing things
all at once and such. That is, rather than saying:

	"/usr/share/doc w/ symlinks from /usr/doc until woody, at which point
	just /usr/share/doc",

or	"/usr/share/doc w/ symlinks" in potato.
	No. Wait.
	"just /usr/share/doc" in woody.

We say

	"Documentation must be accessible from /usr/doc/<package>.

	 In order to ease the transition to FHS, packages should
	 put documentation in /usr/share/doc/<package>, and install a
	 symlink from /usr/doc/<package> -> /usr/share/doc/<package>. Due
	 do a dpkg bug, this symlink should not be included in the package
	 itself, but created by the maintainer scripts like so:


To the technical committee:

I'd appreciate it if you'd consider the above as a possible resolution
to the /usr/share/doc issue. I'd even go so far as to appreciate it if
you'd consider extending it to cover the entire FSSTND/FHS thing to match
existing practice: that is, packages may use either FSSTND or FHS paths,
but should use FHS paths where possible.

When we get to the point where we're sure the transition's worked and there
are only a "few" packages left to convert, we remove the transitional stuff,
to make policy say something like:

	"Documentation must be accessible from /usr/share/doc/<package>."

That is, while we're transitioning, we give ourselves a chance to correct
any mistakes without forcing maintainers to choose between "not conforming
to policy" and "broken" (see later), we give them some leeway.

Lintian could thus report FSSTND errors as a "D:" for deprecated error rather
than an "E:" for "the maintainer is an eee-diot" error.

Anyway, I think this is a better way of designing policy. [1]

Thirdly, people might like to refer to Bug#42741 as an example of why
"just having some docs in one place and others in another" is painful.

Fourth, Raul also points out that debian-policy isn't a constitutional
body, it can only act under the auspices of the technical committee. That
is, just because we reach a consensus on -policy how to deal with an
issue, we can't suddenly declare 1000s of packages [2] buggy --- we're
just individual developers, we can only worry about our own packages. I
agree with Raul in that that situation isn't really -right-, the -policy
group should definitately be able to make policy when we reach a consensus
on an issue, and I think his response to that: that the tech ctte should
rubberstamp issues reached by consensus.

Anyway, I figured it might be nice to say something pleasant about what
the technical committee's been doing rather than just poking fun at it
for a change.

Insert standard "just my opinion" disclaimers here.


[0] master:~klee/debian-ctte.mbox.gz

    I'm not sure that that archive should be public or not, but at the
    moment there's no other way of seeing what the technical committe is
    doing. My apologies for the violation of etiquette -- I'm desperately
    hoping that if I forgive yours, you'll forgive mine.

[1] Although "mustn't declare _any_ packages as being buggy" is much too
    strong, and makes it painful to make particularly meaningful policy.

[2] *blink*. That was *meant* to be an exaggeration.

Anthony Towns <aj@humbug.org.au> <http://azure.humbug.org.au/~aj/>
I don't speak for anyone save myself. PGP encrypted mail preferred.

 ``The thing is: trying to be too generic is EVIL. It's stupid, it 
        results in slower code, and it results in more bugs.''
                                        -- Linus Torvalds

Attachment: pgp18SnSrJrpj.pgp
Description: PGP signature

Reply to: