X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=a09903cfd840dcdd2035f96644ebf1d09a5a1873;hb=5381651c352723b79a2c71528f5fd0670d826725;hp=9c8d5d6a6f048355925e9fa4e269ef524dda6f76;hpb=6f3c73edc59b7686a907eb254d85d427abd30ad5;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index 9c8d5d6..a09903c 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -7,7 +7,7 @@ %dynamicdata; - + @@ -252,7 +252,7 @@ Version 4 (primary) keys can either use the RSA or the DSA algorithms, so this has nothing to do with GnuPG's question about "which kind of key do you want: (1) DSA and Elgamal, (2) DSA (sign only), (5) RSA (sign only)". If you don't have any special requirements just pick -the defailt. +the default.
The easiest way to tell whether an existing key is a v4 key or a v3
(or v2) key is to look at the fingerprint:
@@ -474,7 +474,9 @@ Send an gpg-signed email about why you are leaving the project to
&email-debian-private;.
-If the source NMU (non-maintainer upload) fixes some existing bugs,
-these bugs should be tagged fixed in the Bug Tracking
-System rather than closed. By convention, only the official package
-maintainer or the original bug submitter close bugs.
-Fortunately, Debian's archive system recognizes NMUs and thus marks
-the bugs fixed in the NMU appropriately if the person doing the NMU
-has listed all bugs in the changelog with the Closes:
-bug#nnnnn syntax (see for
-more information describing how to close bugs via the changelog).
-Tagging the bugs fixed ensures that everyone knows that the
-bug was fixed in an NMU; however the bug is left open until the
-changes in the NMU are incorporated officially into the package by
-the official package maintainer.
+Bugs fixed by source NMUs used to be tagged fixed instead of closed,
+but since version tracking is in place, such bugs are now also
+closed with the NMU version.
Also, after doing an NMU, you have to send
the information to the existing bugs that are fixed by your NMU,
@@ -3322,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
@@ -3340,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.
+There are additional fields for the location of the Version Control System
+in
+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).
+
+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
The world is made of men and women. Please use gender-neutral
-constructions in your writing. This is not Political Correctness, this
-is showing respect to all humanity.
+constructions in your writing.
+The extended description should never include a question.
+
For specific rules depending on templates type (string, boolean,
etc.), please read below.
@@ -4480,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)
-
+A debug package is a package with a name ending in "-dbg", that contains
+additional information that gdb can use. Since Debian binaries are
+stripped by default, debugging information, including function names and
+line numbers, is otherwise not available when running gdb on Debian binaries.
+Debug packages allow users who need this additional debugging information to
+install it, without bloating a regular system with the information.
+
+It is up to a package's maintainer whether to create a debug package or
+not. Maintainers are encouraged to create debug packages for library
+packages, since this can aid in debugging many programs linked to a
+library. In general, debug packages do not need to be added for all
+programs; doing so would bloat the archive. But if a maintainer finds
+that users often need a debugging version of a program, it can be
+worthwhile to make a debug package for it. Programs that are core
+infrastructure, such as apache and the X server are also good candidates
+for debug packages.
+
+Some debug packages may contain an entire special debugging build of a
+library or other binary, but most of them can save space and build time
+by instead containing separated debugging symbols that gdb can find and
+load on the fly when debugging a program or library. The convention in
+Debian is to keep these symbols in
+The debugging symbols can be extracted from an object file using
+"objcopy --only-keep-debug". Then the object file can be stripped, and
+"objcopy --add-gnu-debuglink" used to specify the path to the debugging
+symbol file.
+The dh_strip command in debhelper supports creating debug packages, and
+can take care of using objcopy to separate out the debugging symbols for
+you. If your package uses debhelper, all you need to do is call
+"dh_strip --dbg-package=libfoo-dbg", and add an entry to debian/control
+for the debug package.
+
+Note that the Debian package should depend on the package that it
+provides debugging symbols for, and this dependency should be versioned.
+For example:
+
+