X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=a09903cfd840dcdd2035f96644ebf1d09a5a1873;hb=5381651c352723b79a2c71528f5fd0670d826725;hp=ee8366f94e4ea104353d703a3bae9521ef0acef3;hpb=4920b9b195ea26e6fd12f9ff84dacb7fa01f0a73;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index ee8366f..a09903c 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -7,7 +7,7 @@ %dynamicdata; - + @@ -3314,7 +3314,8 @@ quite easy: Setup the co-maintainer with access to the sources you build the package from. Generally this implies you are using a network-capable version control system, such as CVS or -Subversion.

+Subversion. Alioth (see ) provides such +tools, amongst others.

@@ -3332,9 +3333,32 @@ Using the PTS (), the co-maintainers should subscribe themselves to the appropriate source package.

-

-Collaborative maintenance can often be further eased by the use of -tools on Alioth (see ). +

+Another form of collaborative maintenance is team maintenance, which is +recommended if you maintain several packages with the same group of +developers. In that case, the Maintainer and Uploaders field of each +package must be managed with care. It is recommended to choose between +one of the two following schemes: + + +

+Put the team member mainly responsible for the package in the Maintainer +field. In the Uploaders, put the mailing list address, and the team members +who care for the package. + + +

+Put the mailing list address in the Maintainer field. In the Uploaders +field, put the team members who care for the package. +In this case, you must make sure the mailing list accept bug reports +without any human interaction (like moderation for non-subscribers). + + +

+In any case, it is a bad idea to automatically put all team members in +the Uploaders field. It clutters the Developer's Package Overview listing +(see ) with packages one doesn't really care for, and +creates a false sense of good maintenance. @@ -3928,6 +3952,59 @@ until that is available. /^ Homepage: [^ ]*$/, as this allows packages.debian.org to parse it correctly.

+ + + Version Control System location +

+There are additional fields for the location of the Version Control System +in debian/control. + XS-Vcs-Browser +

+Value of this field should be a http:// URL pointing to a +web-browsable copy of the Version Control System repository used to +maintain the given package, if available. +

+The information is meant to be useful for the final user, willing to +browse the latest work done on the package (e.g. when looking for the +patch fixing a bug tagged as pending in the bug tracking +system). + XS-Vcs-* +

+Value of this field should be a string identifying unequivocally the +location of the Version Control System repository used to maintain the +given package, if available. * identify the Version Control +System; currently the following systems are supported by the package +tracking system: arch, bzr (Bazaar), cvs, +darcs, git, hg (Mercurial), mtn +(Monotone), svn (Subversion). It is allowed to specify different +VCS fields for the same package: they will all be shown in the PTS web +interface. +

+The information is meant to be useful for a user knowledgeable in the +given Version Control System and willing to build the current version of +a package from the VCS sources. Other uses of this information might +include automatic building of the latest VCS version of the given +package. To this end the location pointed to by the field should better +be version agnostic and point to the main branch (for VCSs supporting +such a concept). Also, the location pointed to should be accessible to +the final user; fulfilling this requirement might imply pointing to an +anonymous access of the repository instead of pointing to an +SSH-accessible version of the same. +

+In the following example, an instance of the field for a Subversion +repository of the vim package is shown. Note how the +URL is in the svn:// scheme (instead of svn+ssh://) and +how it points to the trunk/ branch. The use of the +XS-Vcs-Browser field described above is also shown. + + Source: vim + Section: editors + Priority: optional + <snip> + XS-Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim + XS-Vcs-Browser: http://svn.debian.org/wsvn/pkg-vim/trunk/packages/vim + + @@ -4423,6 +4500,8 @@ Don't be too verbose. User tend to ignore too long screens. because that means that in the classical dialog interface, people will need to scroll, and lot of people just don't do that.

+The extended description should never include a question. +

For specific rules depending on templates type (string, boolean, etc.), please read below. @@ -4475,8 +4554,6 @@ Below are specific instructions for properly writing the Description question is rather long (remember that translations are often longer than original versions) - The extended description should not include a question. - Again, please avoid referring to specific interface widgets. A common mistake for such templates is "if you answer Yes"-type constructions.