X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=0b0de53fac9614ff1b7301e56bd6819a400ff0e0;hb=d8f60cb36cd4fd22d02851d4465749f4233391da;hp=0345fa47395d070d110fbc539e89f9da242490ee;hpb=c94af677b6d9e6158f0bfdca124c493eef3050a6;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index 0345fa4..0b0de53 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -5,7 +5,7 @@ %commondata; - + @@ -49,7 +49,7 @@ merchantability or fitness for a particular purpose. See the GNU General Public License for more details.
A copy of the GNU General Public License is available as &file-GPL; in
-the Debian GNU/Linux distribution or on the World Wide Web at
-When you know how you want to contribute to the Debian Project, you
+When you know how you want to contribute to &debian-formal;, you
should get in contact with existing Debian maintainers who are working
on similar tasks. That way, you can learn from experienced developers.
For example, if you are interested in packaging existing software for
@@ -132,22 +132,23 @@ these tasks and submit patches and improvements.
-Before you decide to register with the Debian Project, you will need
-to read all the information available at the
The process of registering as a developer is a process of verifying
-your identity and intentions, and checking your technical skills.
-As the number of people working on Debian has grown to over
+your identity and intentions, and checking your technical skills. As
+the number of people working on &debian-formal; has grown to over
&number-of-maintainers; people and our systems are used in several
very important places we have to be careful about being compromised.
Therefore, we need to verify new maintainers before we can give them
@@ -184,7 +185,7 @@ or high-powered spy techniques. See for more
information on maintaining your public key.
Debian uses the
-Due to export restrictions by the United States government some Debian
-packages, including
Some countries restrict the use of cryptographic software by their
citizens. This need not impede one's activities as a Debian package
maintainer however, as it may be perfectly legal to use cryptographic
products for authentication, rather than encryption purposes (as is
-the case in France). The Debian Project does not require the use of
+the case in France). &debian-formal; does not require the use of
cryptography qua cryptography in any manner. If you live in a
country where use of cryptography even for authentication is forbidden
then please contact us so we can make special arrangements.
-When you are ready to apply, you need an existing Debian maintainer
+To apply as a new maintainer, you need an existing Debian maintainer
to verify your application (an advocate). After you have
-contributed to the Project and when you want to apply to become a
+contributed to Debian for a while, and you want to apply to become a
registered developer, an existing developer with whom you
have worked over the past months has to express his belief that you
-can contribute to the Project successfully.
+can contribute to Debian successfully.
When you have found an advocate, have your GPG key signed and have
already contributed to Debian for a while, you're ready to apply.
@@ -237,7 +233,7 @@ name="applications status board">.
For more details, please consult
If you notice that a package is lacking maintenance, you should
make sure the maintainer is active and will continue to work on
-their packages. Try contacting them yourself.
+his packages. Try contacting him yourself.
If you do not get a reply after a few weeks you should collect all
-useful information about this maintainer. Start by logging in to
-the
Send all this information to &email-debian-qa;, in order to let the
QA people do whatever is needed.
@@ -427,7 +423,10 @@ discussions amongst Debian developers. It is meant to be used for
posts which for whatever reason should not be published publically.
As such, it is a low volume list, and users are urged not to use
&email-debian-private; unless it is really necessary. Moreover, do
-not forward email from that list to anyone.
+not forward email from that list to anyone. Archives of this
+list are not available on the web for obvious reasons, but you can see
+them using your shell account master.debian.org and looking
+in the
&email-debian-email; is a special mailing list used as a grab-bag
for Debian related correspondence such as contacting upstream authors
@@ -478,7 +477,7 @@ full, suspicious activity, or whatever, send an email to
The ftp-master server, ftp-master.debian.org (or
auric.debian.org), holds the canonical copy of the Debian
-archive (excluding the non-U.S. packages). Generally, package uploads
+archive (excluding the non-US packages). Generally, package uploads
go to this server; see .
Problems with the Debian FTP archive generally need to be reported as
@@ -568,7 +567,7 @@ id="&url-devel-machines;">.
-The Debian GNU/Linux distribution consists of a lot of Debian packages
+The &debian-formal; distribution consists of a lot of Debian packages
(.deb's, currently around &number-of-pkgs;) and a few
additional files (documentation, installation disk images, etc.).
@@ -607,10 +606,11 @@ further into subsections.
The main section of the Debian archive is what makes up the
-official Debian GNU/Linux distribution.
-The main section is official because it fully complies with
-all our guidelines. The other two sections do not, to different degrees;
-as such, they are not officially part of Debian GNU/Linux.
+official &debian-formal; distribution. The
+main section is official because it fully complies with all
+our guidelines. The other two sections do not, to different degrees;
+as such, they are not officially part of
+&debian-formal;.
Every package in the main section must fully comply with the
-Debian GNU/Linux 1.3 is only available as i386. Debian 2.0
+&debian-formal; 1.3 is only available as i386. Debian 2.0
shipped for i386 and m68k architectures. Debian 2.1
ships for the i386, m68k, alpha, and
sparc architectures. Debian 2.2 adds support for the
@@ -771,7 +771,7 @@ until the distribution is prepared for release, as decided by the
release manager. At the end of the last test cycle, the
testing distribution is renamed to stable,
overriding the old stable distribution, which is removed at
-that time (although they can be found at archive-host;).
+that time (although it can be found at &archive-host;).
This development cycle is based on the assumption that the
unstable distribution becomes stable after passing a
@@ -870,7 +870,7 @@ symbolic links for stable, testing, and
If you want to create a new package for the Debian distribution, you
should first check the
+Changes that you make to the package need to be recorded in the
+
+The
+Changelog entries can be used to automatically close Debian bugs when
+the package is installed into the archive. See .
+
+It is conventional that the changelog entry notating of a package that
+contains a new upstream version of the software looks like this:
+
+There are tools to help you create entries and finalize the
+
@@ -1106,25 +1139,33 @@ To upload a package, you need a personal account on
official maintainer. If you use
Note: Do not upload to ftp-master packages
-containing software that is export-controlled by the United States
-government, nor to the overseas upload queues on chiark or
-erlangen. This prohibition covers almost all cryptographic
-software, and even sometimes software that contains ``hooks'' to
-cryptographic software, such as electronic mail readers that support
-PGP encryption and authentication. Uploads of such software should go
-to non-us (see ). If you are not
-sure whether U.S. export controls apply to your package, post a
+containing software that is patent-restricted by the United States
+government, nor any cryptographic packages which belong to
+contrib or non-free. If you can't upload it to
+ftp-master, then neither can you upload it to the overseas
+upload queues on chiark or erlangen. Uploads of
+such software should go to non-us (see ). If you are not sure whether U.S. patent
+controls or cryptographic controls apply to your package, post a
message to &email-debian-devel; and ask.
-You may also find the Debian package
After uploading your package, you can check how the archive maintenance
software will process it by running
As discussed above, export controlled software should not be uploaded
-to ftp-master. Instead, use
-The program
You can check your upload the same way it's done on ftp-master,
with:
Note that U.S. residents or citizens are subject to restrictions on
-export of cryptographic software. As of this writing, U.S. citizens are
-allowed to export some cryptographic software, subject to notification
-rules by the U.S. Department of Commerce.
+export of cryptographic software. As of this writing, U.S. citizens
+are allowed to export some cryptographic software, subject to
+notification rules by the U.S. Department of Commerce. However, this
+restriction has been waived for software which is already available
+outside the U.S. Therefore, any cryptographic software which belongs
+in the main section of the Debian archive and does not depend
+on any package outside of main (e.g., does not depend on
+anything in non-US/main) can be uploaded to ftp-master
+or its queues, described above.
Debian policy does not prevent upload to non-US by U.S. residents or
citizens, but care should be taken in doing so. It is recommended that
@@ -1159,11 +1203,12 @@ developers take all necessary steps to ensure that they are not
breaking current US law by doing an upload to non-US, including
consulting a lawyer.
-For packages in non-US main or contrib, developers should at least
-follow the
This section is for information only and does not constitute legal
advice. Again, it is strongly recommended that U.S. citizens and
@@ -1853,10 +1898,14 @@ package. When invoked as apt-cache showpkg
-If you decide to remove a package from Incoming, it is nice
-but not required to send a notification of that to the appropriate
-announce list (either &email-debian-changes; or
-&email-debian-devel-changes;).
+In the past, it was possible to remove packages from incoming.
+With the introduction of the New Incoming system this is no longer
+possible. Instead, you have to upload a new revision of your package with
+a higher version as the package you want to replace. Both versions will be
+installed in the archive but only the higher version will actually be
+available in unstable since the previous version will immediately
+be replaced by the higher. However, if you do proper testing of your
+packages, the need to replace a package should not occur too often anyway.
@@ -1930,16 +1979,16 @@ Maintainers interact with the BTS via email addresses at
bugs.debian.org. Documentation on available commands can be
found at
Some find it useful to get periodic reports on open bugs. You can add
a cron job such as the following if you want to get a weekly email
outlining all the open bugs against your packages:
This section contains a rough overview of the tools available to
-maintainers. These tools are meant to help convenience developers and
-free their time for critical tasks.
+maintainers. The following is by no means complete or definitive, but
+just a guide to some of the more popular tools.
+
+Debian maintainer tools are meant to help convenience developers and
+free their time for critical tasks. As Larry Wall says, there's more
+than one way to do it.
Some people prefer to use high-level package maintenance tools and
some do not. Debian is officially agnostic on this issue; any tool
@@ -2098,7 +2151,8 @@ endorse any particular tool to the exclusion of a competing tool.