[Fedora-packaging] Rewording of Review Guidelines

[Hans Ulrich Niedermann]

Thorsten Leemhuis <fedora at leemhuis.info> writes:

> can someone from the PC please reword
> http://fedoraproject.org/wiki/Packaging/ReviewGuidelines
> slightly? We had this earlier today here in #fedora-extras:
>
> ndim> '"The primary Reviewer can be any current package owner, unless
> the Contributor is a first timer."; What does that mean? I can only make
> official reviews after I maintain two packages?'

That was me, and I now know why I didn't understand it.

The ReviewGuidelines page deals with two persons: The "Contributor"
and the "Reviewer".

The section on the "Reviewer" contains the phrase cited above,
referring to the "Contributor" section immediately above it, but I did
not make the connection that the "Contributor" mentioned in the
"Reviewer" section was the same one explained in the section above.

Unfortunately, there is a humongously large screenshot image
(1600x1150) between those two sections disrupting the text and layout
so much that one cannot see anything of the previous section.

Already having been sponsored, I was looking for information how I
could do reviews myself, so I quickly skipped the "Contributor"
section, got my mind erased by the image, and then stumbled on the
"Reviewer" section, having forgotten that the person who has submitted
his package for review is called "Contributor" here. As the "Reviewer"
also is a contributor to Fedora... I became a little confused.

So there are two problems here:

  1. "Contributor" is not self explanatory:
     Both the person who submitted his package for review and the
     "Reviewer" are contributors to the Fedora Project.

  2. The screenshot is too large (much too wide).

Fixing 1. may be difficult, because the wording may be referenced from
elsewhere. However, then we should at least make the difference
between "Contributor" and "contributor" clear, and make the screenshot
small enought that it doesn't completely disrupt the text flow.

I have created a gimped version of the screenshot which has been
reduced to 872x987 from the original 1600x1150:
  http://es.lauft.net/fedora/sample-review-ndim.png
That may still not be enought, but IMHO it is a lot better.

> Maybe something like
>
> "The primary Reviewer can be any current package owner. Only packages
> that are from first time contributors need to be reviewed from sponsors."
>
> would be better.

This should be "Contributors" with capital "C".

The whole paragraph reads:

 | A Reviewer is defined as the person who chooses to review a
 | package. For the sake of clarity, one person takes ownership of the
 | review. Other people are encouraged to comment on the review as
 | well, either in the bug or on the mailing list. The primary
 | Reviewer can be any current package owner, unless the Contributor
 | is a first timer.

I'd suggest something like

 | A Reviewer is defined as the person who chooses to review a
 | package. For the sake of clarity, one person takes ownership of the
 | review. Other people are encouraged to comment on the review as
 | well, either in the bug or on the mailing list. The primary
 | Reviewer for the Contributor's first package must be a sponsor; for
 | the Contributor's further packages any current package owner can be
 | the primary Reviewer.

or something which repeats the structure of the sentence:

 | A Reviewer is defined as the person who chooses to review a
 | package. For the sake of clarity, one person takes ownership of the
 | review. Other people are encouraged to comment on the review as
 | well, either in the bug or on the mailing list. For the
 | Contributor's first package, the primary Reviewer must be a
 | sponsor. For the Contributur's further[1] packages, the primary
 | Reviewer can be any current package owner.

 [1] A native speaker of English should choose a better word here.

Together with a smaller screenshot, this should create a readable
document. :-)

I hope this doesn't make things more complicated than they deserve to
be.

Gruß,

Uli
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 188 bytes
Desc: not available
Url : http://lists.fedoraproject.org/pipermail/packaging/attachments/20060908/c076d7d6/attachment.bin