Re: dep3 nit-picks
[ moving to -devel from a private discussion to have more feedback ]
Daniel was asking me how several unstructured paragraphs are supposed to
be treated for the Description field. I told him that the description is
the concatenation of all of them. Do other people agree with Daniel that
the points that he raises need clarifications?
DEP URL for reference: http://dep.debian.net/deps/dep3/
On Thu, 05 Nov 2009, Daniel Kahn Gillmor wrote:
> On 11/05/2009 02:45 AM, Raphaël Hertzog wrote:
> > It's the concatenation of all of them. Can you suggest a wording that
> > would make it more clear?
>
> what about:
>
> Any parser that expects those fields in patch headers should also
> accept non-structured content and simply append the non-structured
> content to the value of the `Description` field.
Looks reasonable.
> A few more nit-picks that i just noticed:
>
> 2) there is a distinction made between the header and the pseudo-header,
> but it's not clear if the placement of fields in one or the other has
> any meaning. Is information in the pseudo-header expected to be treated
> any differently than information in the regular header?
>
> I think the answer is "no, there is no difference", but the document
> never says that explicitly, and the act of naming the second header
> implies that the name will be used elsewhere in the document, though it
> never is. (as someone immersed in debian lore, i assume that the act of
> naming the pseudo-header is to give readers a point of reference to the
> BTS, the other place where two sets of 2822-like headers show up -- but
> that's implicit in the context, and not explicit in the document).
How can we make that explicit? Would replacing « (the
“pseudo-header”) » with « (sometimes called the “pseudo-header”
in other contexts) » be appropriate?
> 3) multiple copies of a given field? section 3.6 of RFC 2822 gives
> counts of the number of times a given field may appear in a header:
>
> http://tools.ietf.org/html/rfc2822#section-3.6
>
> The only field in DEP3 that explicitly says it can be used multiple
> times is Reviewed-By or Acked-By
Not true, it's also said for Bug/Bug-<vendor>/Author/From
> -- but i don't see anything else that
> says that the other fields *cannot* be used multiple times.
Do we really need to make that explicit?
Description/Subject/Forwarded/Last-Update/Origin are expected to be
unique.
> 4) Reviewed-By is semantically unclear. I can review something and
> decide it's a bad idea. In that case, it has been reviewed by dkg, but
> would it really be Reviewed-By: dkg? probably not (i'm assuming there's
> considered to be no semantic difference between Reviewed-By and
> Acked-By). I'm not suggesting that we change the header label
> necessarily (and i don't know why it was changed from Signed-off-by to
> Reviewed-by in the first place -- can you point me to any discussion
> about that change?), but if "Reviewed-By" is going to have any sort of
> "stamp of approval" connotation, it should be explicitly noted someplace.
It has an implicit meaning of approval yes. If the review was negative, it
should not be added or it should be clarified in the Description what the
reviewer's comments were (always a good idea).
Proposition of patches welcome. Please search the debian-devel archives
for the discussion about the rename. It was in june IIRC. Signed-off-by
has precisely been dismissed because it doesn's have this approval
connotation.
Cheers,
--
Raphaël Hertzog
Reply to: