Bug#108416: Format of short description should be mandated
Chris Waters wrote:
> On Sat, Aug 18, 2001 at 11:06:36PM -0500, Branden Robinson wrote:
> > Well, if I downgrade my "must not"'s to "should not"'s, would you second
> > the proposal?
I'm not sure, I have a terrific mail backlog and skimmed your proposal.
Chris makes some good points too, in the parts of his mail I have
deleted.
> That wasn't addressed to me, but my reaction is the same as it was to
> the original proposal: this doesn't belong in policy. It belongs in
> dev-ref or the packaging manual, or some similar set of guidelines for
> maintainers.
> The word "typically" reveals the flaw here, I think. "It should be
> unless it shouldn't be." This is clearly just a guideline, and not
> even a firm one, and thus, definitely doesn't belong in policy (even
> if other parts of the proposal are accepted).
Please bear section 5.7.1 of debian policy in mind. Policy already has a
lot of guidelines about package descriptions. Many of them require the
application of common sense to be useful, but this is not unique in this
part of debian policy, and I belive that having them in a document that
every developer reads (I hope) has caused more good than harm.
> > * expand acronyms [...]
>
> Generally, but not necessarily always, a good idea. IMO. I'd like to
> see this as a guideline. I do not want to see it made policy.
In this specific case, I really like what policy says now:
The description field needs to make sense to anyone, even people
who have no idea about any of the things the package deals with.
The acronym guidline falls out of this naturally. Maybe another footnote
could state it explicitly.
> Here I strongly disagree. I think the one line description should be
> targetted at people who _don't_ have any idea what the package is.
I think policy agrees with you, see quote above.
> > [should not] repeat the package name [...]
>
> Hmm, if any part of this proposal belongs in policy, it's this. But I
> still think a guideline is sufficient.
Do not include the package name in the synopsis line.
Already in policy.
> > [must not] be longer than 80 chars.
>
> Finally something I agree with! :-)
Already in policy.
--
see shy jo
Reply to: