Re: use README.source to describe whether committing to VCS is desired
On Wed, Dec 23 2009, Russ Allbery wrote:
> Stefano Zacchiroli <zack@debian.org> writes:
>> On Wed, Dec 23, 2009 at 11:41:07PM +0900, Charles Plessy wrote:
>
>>> + <p>
>>> + In addition, <file>debian/README.source</file> may also be
>> ^^^
>> I'd rather use "should" if, as it seems from the few early messages,
>> there is consensus on this change.
>
>>> + used to describe how a source package is managed by its
>>> + maintainers, for instance by detailing the write permissions
>>> + on the version control system in which it is stored, or to
>>> + provide a link to the group policy it follows.
>>> + </p>
>>> </sect>
>>> </chapt>
>
> "should" implies that every Debian package should have such file, but
> I don't think the vast majority of Debian packages need such a thing.
> Many have no special requirements beyond common best practices, and
> even the ones with a VCS provide sufficient information in the Vcs-*
> fields for the most part.
>
> The largest objection we've gotten to README.source is the addition of
> boilerplate files to lots of packages, and in retrospect that was
> probably a mistake (although format 3.0 mostly makes this go away
> again). I don't really want to add something else similar. I'd
> rather err on the side of telling maintainers not to bother unless
> there's something particularly important to say.
For what it is worth, I agree with this assessment. There ought
to be a place where a maintainer might, if they so desire, add more
information on how development of the source package is done, and the
policies that the maintainer follows, but policy should not put pressure
on any maintainer that does not wish to do so to add a
README.source. In other words, this information should be an opt-in
entity, since it is not required for integration of the package into
the OS, and not having the information will have only a minimal impact
on most users.
>
>>> <p>
>>> + Instruction on how to use and manage a Debian source package
>>> + can be written in a <file>debian/README.source</file>
>>> + documentation file.
>>> + </p>
>
>> IMO, this is too vague, I'd like to see VCS mentioned as a concept,
>> otherwise the reader will likely miss the point of this change.
>
> Also, "use" seems a bit odd to me. Hopefully all Debian source packages
> are used in exactly the same way: by building binary packages from them.
> :) I think the intention is more specifically to document anything
> unusual about maintaining the package that others need to be aware of.
As I have been only superficially been following this, I am
uncertain about what _kinds_ of documentation we are talking about
here. The layout and policies are covered by the change above, so what
else would this change be referring to?
manoj
--
Eeny, Meeny, Jelly Beanie, the spirits are about to speak! Bullwinkle
Moose
Manoj Srivastava <srivasta@acm.org> <http://www.golden-gryphon.com/>
1024D/BF24424C print 4966 F272 D093 B493 410B 924B 21BA DABB BF24 424C
Reply to: