Maintainers, teams, Uploaders, DMs, DDs, etc.

[Ian Jackson <ijackson@chiark.greenend.org.uk>]

It's evident from recent conversations in various places that we are
confused about:
 - what Maintainer and Uploaders mean
 - who is entitled to do what when
 - in some cases, the distinction between ability and permission
etc.


I'm going to try to set out my understanding of the current best
practices, with some open questions and suggestions for improvement.
I'm proposing this as an alternative to the existing plan to change
the way DM permission works.

But firstly I want to explain an important principle: the distinction
between ability and permission.  In any complex collective endeavour,
there will be both access controls that actually prevent some people
from taking certain acts, and ideas (whether stated formally and
clearly, or informally and vaguely) about what should be done when and
by whom.

Access restrictions are annoying to implement and work with so they
should be minimised where possible - but they are a necessary backstop
to prevent abuse.  In general access restrictions need to be flexible
enough that it is possible to revoke the permissions of someone who is
using their technical ability in ways that are considered undesirable
by whoever is supposed to be in charge.  But, provided that there are
sufficient facilities for reverting misdeeds and mistakes, they do not
need to be more complex than that.

So for example, DDs have enormous theoretical power but there are
strong and well documented social controls on how they should exercise
that.  I think as a matter of principle that the same principle should
apply to DMs: it is easy to remove a misbehaving DM from Uploaders.
So it is not necessary to have technical measures that prevent a DM
mentioned in Uploaders from violating the package's uploading rules,
bypassing review processes, or whatever.  Instead, when a package team
or lead maintainer accepts someone into Uploaders we should clearly
communicate to the new uploader what is expected of them, and then we
should trust them to do as we have asked.


So firstly, let me go through the actual places where we as a project
store information about the maintenance structure of a package:

 * Maintainer field
 * Uploaders field
 * DM-Upload-Allowed field
 * The DD keyring
 * The DM keyring
 * Team membership lists kept elsewhere (eg, a team webpage or
   wiki page, mailing list membership, or whatever)
 * Team practices/processes/policy agreements, documents, etc.
   (which might include anything from informal private emails to
   formal process and governance documents)


The questions that need to be answered for a package are:

 * Who is (supposedly) doing most of the work.

 * Who makes final decisions about the package; this includes
   arbitraring disputes, delegating authority, revoking such
   delegation, etc.

   The identity of the people with this responsibility needs to be
   accessible to the project as a whole so that people who are
   unfamiliar with the package can see whose opinions are definitive.
   This information does not normally need to be used automatically by
   the project's support infrastructure.

   I'm going to call these people the maintainers of the package.
   They might be DDs, DMs, or contributors without a key in the
   keyring.

   Currently this information is sometimes in the Maintainer field;
   sometimes in both the Uploaders and Maintainers fields; and
   sometimes somewhere else completely (eg a team wiki page).

   Normally the maintainers would be the people who are doing most of
   the work.  Sometimes we have provisional maintainers who are
   neither DD or DM; in those cases the maintainer works under the
   supervision of their sponsors.

c. Who is entitled to prepare a non-NMU upload of the package.

   This information needs to be accessible to the project as a whole.

   Particularly a potential drive-by sponsor needs to know whether the
   upload they are sponsoring is by someone entitled to prepare such
   an upload.  And the archive software needs to know whether to
   permit an upload.

   Currently this information is sometimes in the Maintainer field;
   sometimes in both the Uploaders and Maintainers fields; and
   sometimes somewhere else completely (eg a team wiki page).

d. Who is morally entitled to perform various other actions with
   respect to the package, such as manipulating bugs, committing to
   its vcs, etc.

   This information does not need to be available to people outside
   the team involved with the package.  If disputes arise they can be
   dealt with by the maintainers, and if necessary the maintainers can
   invoke various enforcement mechanisms to stop misbheaviour.

e. What process should someone preparing a non-NMU upload follow?

   Eg, is there a VCS that everything should be committed to ?  Are
   non-emergency uploads supposed to be reviewed somewhere ?  Are some
   of the people who are entitled to upload supposed only to do so
   after explicit indication by someone more senior that they should
   do so ?

   Again this information doesn't generally need to be available to
   people outside the packaging team.  However, if there are
   significant and important processes that should be followed, a
   drive-by sponsor should be able to find them easily so that they
   can double-check that the person preparing the upload (the sponsee)
   seems to be doing the right thing.

   Currently this information is, if available at all, to be found on
   various team wiki pages etc. which may be hard to discover.

f. Are there specific things that an NMUer should watch out for ?

   Currently we have no general way of finding these.  The closes is
   the LowThresholdNmu wiki page.

g. For a package in alioth collab-maint, how is the VCS workflow
   organised and who is expected to push to which branches ?

   Currently we have no general way of finding these.


As an example of some common patterns:

 * Individual DD or DM maintainer, perhaps with co-maintainers.  The
   single individual principal maintainer is listed in Maintainer and
   makes all decisions.  Co-maintainers are listed in Uploaders and
   may make their own uploads and may in general make decisions where
   not contradicted by the principal maintainer.  There may or may not
   be any information for NMUers.

 * Individual non-DM maintainer, co-maintainers including at least one
   usual DD or DM sponsor.  The maintainer is listed in Maintainer;
   the usual sponsor(s) are listed in Uploaders.  The principal
   maintainer makes decisons as before; however their authority is
   weakened by their inability to upload without sponsorship.  In
   practice this means that the principal maintainer does the work but
   the co-maintainers have supervisory authority.

 * Non-DM maintainer(s), drive-by sponsor.  The maintainer(s) are
   listed in Maintainer and Uploaders and makes all decisions in the
   first instance (perhaps with the Maintainer having more authority
   than the Uploaders), but needs the approval of a sponsor to upload.
   The sponsor is supposed to sanity-check the maintainer's work, to
   advise, etc., and generally to supervise, but does not take on
   primary responsibility.

 * Team maintenance.  The team (a mailing list address) is listed in
   Maintainers.  The formal membership of the maintenance team - ie,
   who can make decisions - may be discerned by reading some wiki or
   web page, or might be visible by looking at Uploaders.

   People outside the team may have some difficulty seeing who is in
   charge.  But such teams at least don't normally need external
   sponsorship for uploads.


I think the key problems we have here are:

 * The relative seniority of members of Maintainer vs Uploaders is not
   always clear.  This is complicated by the fact that it is not
   possible to list more than one person in Maintainers.

 * It can be difficult for non-team members to find out who is in the
   maintenance team for a team maintained package and what they are
   supposed to be allowed to do.

 * Our documentation (eg the dev ref) does not always clearly spell
   out the sociopolitical meanings of the technical data fields.

 * The treatment of maintainers/uploaders wrt package email (eg, from
   the bts and pts) is inconsistent, so that if your status changes
   you need to fiddle with a lot of email subscriptions.  This is an
   ongoing subject of discussion but we need to understand what we
   think the technical data fields are and what they mean before
   making changes to the email machinery.

 * We do not have a common understanding of who is entitled to hijack
   a package and when they are entitled to do so.  This is a hard and
   controversial problem which deserves considering on its own, and
   will be a distraction for what I'm saying in this message.


I think the first three can be fixed relatively simply.  I propose the
following changes:

1. Change the definition of the Maintainer field to permit multiple
   entries.

   There are currently four different entities (3 humans and a
   corporation) which use a comma in a Maintainer field, in only 13
   different source packages.  None of these commas are essential to
   comprehension (indeed in principle those same entities might have
   to have variants of their identification without commas, suitable
   for use in Uploaders).  All but one of these Maintainer fields are
   already violations of policy 5.6.2 which says that the Maintainer
   field must be in "RFC822 format" (a bit vague, but clearly excludes
   bare commas).

   So this is an easy change.

2. Explicitly state that being listed in Uploaders does not in itself
   imply general authority over the package; general authority is
   reserved to maintainers.

   Uploaders merely implies authority to prepare an new version, and
   if the listed person is capable of doing so, upload it.

   Explicitly state that the authority of Uploaders to prepare and
   upload is subject always to the contents of debian/README.maintain.

3. Introduce a new conventional location for information about a
   maintenance team and a package's maintenance practices,
      debian/README.maintain
   in the source package.

   Explicitly state that this file, if it exists, should be consulted
   by anyone who is preparing or sponsoring a non-NMU upload.
   Explicitly state that the file may contain references to external
   wiki or web pages, or may contain information itself.

   Add a warning that the version in unstable should be regarded as
   definitive, so that someone working in another suite may need to
   check the sid version of the source package.

   Add to the PTS and QA pages a convenient link to the most recent
   version of the file.

4. State that if a package's Maintainer field contains any entity that
   is not an individual, the file debian/README.maintain should exist
   and contain or refer to information sufficient to determine who the
   maintainers of the package are.

   Deprecate Maintainer fields which contain a mixture of humans and
   other things.

5. Introduce a new conventional location for information useful to
   NMUers,
      debian/README.nmu

   Explicitly state that someone preparing or sponsoring an NMU should
   consult this file.  Statements in this file may supplement, but do
   not overrule, the NMU criteria established by the Developers'
   Reference, by the release team, or elsewhere.

   Explicitly state that NMUers are NOT necessarily required to
   consult README.maintain.

I think this should be sufficient for everyone to implement whatever
maintenance practices (and corresponding relationships between
people) they think best.

My point 2 implies a change to way Uploaders and Maintainer is used by
some packages, but for a package whose Maintainer has already told
their Uploader that they are a co-maintainer the co-maintainer already
has the appropriate delegated authority.  And since none of the
technical access control machinery will make decisions differently,
this slight anomaly in the metadata describing who the maintainers are
can be fixed at the maintainers' leisure.

It doesn't seem to me that there is any need to change the archive
machinery to handle DM permissions differently.


Thanks,
Ian.