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

Re: DEP1: Non Maintainer Uploads (final call for review)



On Mon, Aug 11, 2008 at 07:28:53PM -0300, Lucas Nussbaum wrote:
>    Before doing an NMU, consider the following questions:

>      o Do you really fix bugs in your NMU? Fixing cosmetic issues,
>        or changing the packaging style in NMUs is discouraged,
>        unless it is required to fix bugs.

Suggested change:

       o Does your NMU really fix bugs?  Fixing cosmetic issues
         or changing the packaging style in NMUs is discouraged.

The rewording of the first sentence is (IMHO) more natural in English; drop
an unnecessary comma; and omit the "unless it is required to fix bugs": by
definition, a cosmetic change would not be a bugfix, and changing the
packaging *style* is not *required* to fix bugs even though that will be the
preference of some NMUers at times.

>      o Have you clearly expressed your intention to NMU, at least
>        on the BTS? Has the maintainer been notified of it? It is
>        also a good idea to try to contact the maintainer by other
>        means (private email, IRC).

s/on the BTS/in the BTS/

"Has the maintainer been notified of it" -- what's the antecedent of "it"
here?  The intention to NMU?  Perhaps it's better to omit this sentence,
since the following sentence appears to cover everything?

>      o If the maintainer is usually active and responsive, have you
>        tried to contact him? In general it should be considered
>        preferable that a maintainer takes care of an issue himself
>        and that he is given the chance to review and correct your
>        patch, because he can be expected to be more aware of
>        potential issues which an NMUer might miss.

Suggested addition:

  It is often a better use of everyone's time if the maintainer is given an
  opportunity to upload a fix on their own.

>    When doing an NMU, you must first make sure that your intention
>    to NMU is really clear. Then, you must send a patch with the
>    differences between the current package and your proposed NMU to
>    the BTS (the nmudiff script in the devscripts package might be
>    helpful).

s/really //

Avoid gratuitous use of adverbs.

I recommend rewriting the last part of this to avoid a parenthetical; the
current parenthetical is a complete sentence on its own, and should probably
just be taken out of parentheses.

>    Unless you have an excellent reason not to do so, you must then
>    give some time to the maintainer to react (for example, by
>    uploading to the DELAYED queue). Here are some delays that you
>    could use as default values:

"Here are some recommended values to use for delays:"?

>      o Upload fixing only release-critical bugs older than 7 days:
>        2 days

>      o Upload fixing only release-critical and important bugs: 5
>        days

>      o Other NMUs: 10 days

Not consistent with my own recommendations, FWIW; if I'm doing an upload
that fixes /any/ RC bug, I consider other verifiable bugs to be fair game in
the same time frame regardless of their severity.

BTW, one thing that appears to be missing here is a warning against NMUing
for bugs you yourself have filed.  I have seen developers file bugs, set a
high severity on their own, and declare an NMU without any evidence that the
bug has been confirmed or reviewed by a third party.  IME these make for
some of the worst NMUs that are most likely to be reverted, because they are
almost always some other developer's pet issue, which tends to induce a lack
of perspective.

>    Those delays are only examples. In some cases (uploads fixing
>    security issues, trivial bugfixes blocking a transition, ...),
>    it is desirable that the fixed package reaches unstable sooner.

   In some cases, such as uploads fixing security issues or fixes for
   trivial bugs that are blocking a transition, it is desirable [...]

>    Sometimes, release managers decide to allow NMUs with shorter
>    delays for a subset of bugs (e.g release critical bugs older
>    than 7 days). Also, some maintainers listed themselves in the
>    Low Threshold NMU list, and accept that NMUs are uploaded
>    without delay. But even in those cases, it's still a good idea
>    to give the maintainer a few days to react before you upload,
>    especially if the patch wasn't available on the BTS before, or
>    if you know that the maintainer is generally active.

s/release critical/release-critical/

s/listed/list/

s/on the BTS/in the BTS/

>    After you upload an NMU, you are responsible for the possible
>    problems that you might have introduced. You must keep an eye on
>    the package (subscribing to the package on the PTS is a good
>    idea).

s/is a good idea/is a good way to achieve this/ ?

>    This is not a license to perform NMUs thoughtlessly. If you NMU
>    when it is clear that the maintainers are active and would have
>    acknowledged a patch in a timely manner, or if you ignore the
>    recommendations of this document, be warned, there is no
>    protection for you here. You should always be prepared to defend
>    the wisdom of any NMU you perform on its own merits.

s/be warned, there is no protection for you here/your upload may very well
be a cause of conflict with the maintainer/

>   5.11.2. NMUs and debian/changelog

>    Just like any other (source) upload, NMUs must add an entry to
>    debian/changelog, telling what has changed with this upload. The
>    first line of this entry is special, it must be:

>    * Non-maintainer upload

Making this verbatim line a "must" is overly restrictive.  From time to
time, I have occasion to say something like "Non-maintainer upload, with
permission of the maintainer" or "0-day NMU for RC bugfix".  I propose
saying:

   The first line of this entry must explicitly mention that this upload is
   an NMU, e.g.:

      * Non-maintainer upload

>    The version must be the version of the last upload, plus +nmuX,
>    where X is a counter starting at 1. If the last upload was also
>    an NMU, the counter should be increased. For example, if the
>    current version is 1.5-1, then an NMU would get version
>    1.5-1+nmu1. If the current version is 1.5+nmu3 (a native package
>    which has already been NMUd), the NMU would get version
>    1.5+nmu4. If a new upstream version is packaged in the NMU, the
>    debian revision is set to 0, for example 1.6-0+nmu1.

last upload -> last maintainer upload

eliminates ambiguity in the first sentence about whether the version number
should be 1.1-2+nmu1+nmu2 :P

>    This special versioning is needed to avoid stealing one of the
>    package maintainer's version numbers, which might disrupt their
>    work. It also has the benefit of making it visually clear that a
>    package in the archive was not made by the official maintainer.

This seems to overstate the case for this *particular* versioning scheme; we
already had a versioning scheme for non-native packages that avoided
conflicts with the package maintainer's version scheme.  Perhaps:

  A special versioning scheme is needed to avoid disrupting the maintainer's
  work, since using an integer for the Debian revision will potentially
  conflict with a maintainer upload already in preparation at the time of an
  NMU, or even one sitting in the ftp NEW queue.

>    If you upload a package to testing or stable, you sometimes need
>    to "fork" the version number tree. This is the case for security
>    uploads, for example. For this, a version of the form +debXYuZ
>    should be used, where X is the current stable major release
>    number, and Y is the current minor release number for a stable
>    upload, or one higher than that for a testing upload. Z is a
>    counter starting at 1. For example, while Etch (Debian 4.0) is
>    stable, a security NMU to stable for a package at version 1.5-3
>    would have version 1.5-3+deb40u1, while a security NMU to Lenny
>    would get version 1.5-3+deb41u1. This is the case even when it
>    is already known that the next release will be a new major
>    version ; for instance, Lenny will be released as Debian 5.0.

s/ ;.*/./

(don't embed verb tenses that will quickly become dated)

s/while a security/whereas a security/

I'm not really a fan of this bit, and I haven't noticed a whole lot of
discussion of it.  It does guarantee a consistent sort order between binNMUs
and NMUs, so I don't think my non-fandom rises to the level of an objection.

Has anyone from the security team commented on whether they intend to /use/
this scheme?

>   5.11.3. Using the DELAYED/ queue

>    After asking the maintainer for the permission to upload your
>    NMU, it is annoying to have to wait for some time before you
>    actually make the upload.

s/the permission/permission/

"annoying" is not a word I would use in a technical document such as this.
Perhaps:

   Having to wait for a response after you request permission to NMU is
   inefficient, because it costs the NMUer a context switch to come back to
   the issue.

>    The DELAYED queue (see Section 5.6.2, "Delayed uploads") allows
>    the developer doing the NMU to perform all the necessary tasks
>    at the same time. Instead of telling the maintainer that you
>    will upload the updated package in (for example) 7 days, you
>    should upload the package to DELAYED/7 and tell the maintainer
>    that he has 7 days to react. During this time, the maintainer
>    can ask you to delay the upload some more, or cancel your
>    upload.

Join this paragraph to the previous sentence.

s/Instead of/For instance, instead of/; s/ (for example)//

>    The DELAYED queue should not be used to put additional pressure
>    on the maintainer. In particular, it's important that you are
>    available to cancel or delay the upload before the delay expires
>    (the maintainer cannot cancel the upload himself).

s/(/since /; s/)//

>    If you make an NMU to DELAYED, and the maintainer updates his
>    package before the delay expires, your upload will be rejected,
>    because a newer version (the maintainer's one) is already
>    available in the archive. Normally, the maintainer should take
>    care to include your proposed changes (or at least a solution
>    for the problems they address) in that upload.

Better to trim a few commas:

   If you make an NMU to DELAYED and the maintainer updates his package
   before the delay expires, your upload will be rejected because a newer
   version is already available in the archive.

And perhaps s/Normally, the maintainer should/Ideally, the maintainer will/

>   5.11.4. NMUs from the maintainer's point of view

>    When someone NMUs your package, this means they want to help you
>    to keep it in good shape. This saves you work, and gives users
>    fixed packages faster. You can consider asking the NMUer to
>    become a co-maintainer of the package.

"This saves you work" - this is not always true, and I think it should be
qualified or elided.  In particular, I think NMUs for packages where I
already have a new version in preparation in a VCS are usually more work for
me than if I were just given patches in the BTS.  This doesn't mean that the
NMU shouldn't be done - there are definitely cases where having faster fixes
for users *should* outweigh the fact that it makes more work for me in the
long term - but I'd rather not see NMUs justified with false claims.

>    If someone suggests that they could do an NMU on your package,
>    you should be thankful that they want to put time into this,
>    while it is really your responsibility to fix the bug. Receiving
>    an NMU on a package is not a bad thing; it just means that the
>    package is interesting enough for other people to work on it.

This paragraph is all kinds of wrong.  Don't tell me that I *should* be
thankful; that implies that I'm an ingrate even if I have legitimate reasons
for objecting to a particular NMU.  Nor do I agree that receiving an NMU is
never a bad thing, and I don't think the developers at large really believe
this; candy-coating here isn't going to change the reality that sometimes,
an NMU is a sign of a failure of the maintainer to maintain his package, or
a failure of the maintainer and an NMUer to agree.

I don't currently have an alternative wording to offer, but I think this
should be a point of further discussion.

>    When a package has been NMUed, the maintainer should acknowledge
>    it in the next upload. This makes clear that the changes were
>    accepted in the maintainer's packaging, and that they aren't
>    lost again. For this, you must first incorporate the changes
>    into your package, as far as you want to keep them. Make sure to
>    include the NMU's changelog entry (not just the line describing
>    the changes) in your own changelog. This is important to allow
>    the BTS version tracking to work.

"as far as you want to keep them" - but if a maintainer upload /doesn't/
want to keep some of the changes, this may mean that some bugs become
un-fixed.  Is it better then to include the full changelog from the NMU,
which means you have to reopen some bugs in the BTS by hand, or to
cherry-pick from the NMU changelog into your own changelog, which will show
as a branch in the BTS but allow the relevant bugs to be automatically
re-closed?

Consider also the corner case that you revert some changes from the NMU,
include the full NMU changelog as a parent of your upload, and another bug
related to the changes you've reverted has been manually marked in the BTS
as closed in the NMU version.  What process should the maintainer follow to
ensure that this bug doesn't remain wrongly closed in the BTS?

>   5.11.5. Source NMUs vs Binary-only NMUs (binNMUs)

Is this section needed at all, or should Section 5.10.2.1 be sufficient (or
expanded if not)?

>   5.11.6. NMUs vs QA uploads

>    NMUs are uploads of packages which are owned by another
>    maintainer. There is another type of upload where the uploaded
>    package is not yours: QA uploads. QA uploads are uploads of
>    orphaned packages.

s/are owned by another maintainer/have a maintainer other than you/

>    If you want to do an NMU, and it seems that the maintainer is
>    not active, it is wise to check if the package is orphaned. When
>    doing the first QA upload to an orphaned package, the maintainer
>    should be set to Debian QA Group <packages@qa.debian.org>.
>    Orphaned packages which did not have a QA upload yet still have
>    their old maintainer set. There is a list of them at
>    http://qa.debian.org/orphaned.html.

  --> Orphaned packages which did not yet have a QA upload still have

Cheers,
-- 
Steve Langasek                   Give me a lever long enough and a Free OS
Debian Developer                   to set it on, and I can move the world.
Ubuntu Developer                                    http://www.debian.org/
slangasek@ubuntu.com                                     vorlon@debian.org


Reply to: