From: aph Date: Sat, 11 May 2002 20:11:03 +0000 (+0000) Subject: entity'ize master.debian.org, us-upload-dir, non-us-upload-dir X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=cdfe8d781e504566f443d9b05487e32f44f769bf;p=developers-reference.git entity'ize debian.org, us-upload-dir, non-us-upload-dir tagging improvements: replace with for files and directories; since and doesn't look right, work-around with <...> fix some awkward working from recent updates git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@1682 313b444b-1b9f-4f58-a734-7bb04f332e8d --- diff --git a/common.ent b/common.ent index 17cf18e..2d4e4cd 100644 --- a/common.ent +++ b/common.ent @@ -35,6 +35,8 @@ + +/pub/UploadQueue/"> - + There are two types of Debian packages, namely source and binary packages.

-Source packages consist of either two or three files: a .dsc -file, and either a .tar.gz file or both an -.orig.tar.gz and a .diff.gz file. +Source packages consist of either two or three files: a .dsc +file, and either a .tar.gz file or both an +.orig.tar.gz and a .diff.gz file.

If a package is developed specially for Debian and is not distributed -outside of Debian, there is just one .tar.gz file which +outside of Debian, there is just one .tar.gz file which contains the sources of the program. If a package is distributed -elsewhere too, the .orig.tar.gz file stores the so-called +elsewhere too, the .orig.tar.gz file stores the so-called upstream source code, that is the source code that's distributed from the upstream maintainer (often the author of -the software). In this case, the .diff.gz contains the +the software). In this case, the .diff.gz contains the changes made by the Debian maintainer.

-The .dsc lists all the files in the source package together +The .dsc file lists all the files in the source package together with checksums (md5sums) and some additional info about the package (maintainer, version, etc.). @@ -732,28 +732,28 @@ the package (maintainer, version, etc.).

The directory system described in the previous chapter is itself contained within distribution directories. Each -distribution is actually contained in the pool directory in the +distribution is actually contained in the pool directory in the top-level of the Debian archive itself.

To summarize, the Debian archive has a root directory within an FTP server. For instance, at the mirror site, ftp.us.debian.org, the Debian archive itself is contained in /debian, which is a common location -(another is /pub/debian). +(another is /pub/debian).

A distribution is comprised of Debian source and binary packages, and the -respective Sources and Packages index files, containing +respective Sources and Packages index files, containing the header information from all those packages. The former are kept in the -pool/ directory, while the latter are kept in the dists/ -directory of the archive (because of backwards compatibility). +pool/ directory, while the latter are kept in the dists/ +directory of the archive (for backwards compatibility). Stable, testing, and unstable

There are always distributions called stable (residing in -dists/stable), one called testing (residing in -dists/testing), and one called unstable (residing in -dists/unstable). This reflects the development process of the +dists/stable), one called testing (residing in +dists/testing), and one called unstable (residing in +dists/unstable). This reflects the development process of the Debian project.

Active development is done in the unstable distribution @@ -793,8 +793,8 @@ stable distribution is updated every now and then. However, these updates are tested very carefully and have to be introduced into the archive individually to reduce the risk of introducing new bugs. You can find proposed additions to stable in the -proposed-updates directory. Those packages in -proposed-updates that pass muster are periodically moved as a +proposed-updates directory. Those packages in +proposed-updates that pass muster are periodically moved as a batch into the stable distribution and the revision level of the stable distribution is incremented (e.g., ‘3.0’ becomes ‘3.0r1’, ‘2.2r4’ becomes ‘2.2r5’, and @@ -891,16 +891,16 @@ installing them in the Debian archive. It consists of a set of directories and scripts that are installed both on &ftp-master-host; and &non-us-host;.

-Packages are uploaded by all the maintainers into an unchecked +Packages are uploaded by all the maintainers into an unchecked directory. This directory is scanned every 15 minutes by the katie script that verifies the integrity of the package and the cryptographic signature. If the package is considered ready to be installed, it -is moved into an accepted directory. If it is the first upload of -the package then it is moved in a new directory waiting an +is moved into an accepted directory. If it is the first upload of +the package then it is moved in a new directory waiting an approval of the ftpmasters. If the package contains files to be installed -"by-hand" is is moved in the byhand directory waiting a manual +"by-hand" is is moved in the byhand directory waiting a manual installation by the ftpmasters. Otherwise, if any error has been detected, -the package is refused and is moved in the reject directory. +the package is refused and is moved in the reject directory.

Once the package is accepted the system sends a confirmation mail to the maintainer, closes all the bugs marked as fixed by the upload @@ -910,46 +910,45 @@ such URL for packages in the non-US archive) until it is really installed in the Debian archive. This happens only once a day, the package is then removed from incoming and installed in the pool along with all the other packages. Once all the other updates (generating new -Packages and Sources index files for example) have been +Packages and Sources index files for example) have been made, a special script is called to ask all the primary mirrors to update themselves.

-All debian developers have write access to the unchecked +All debian developers have write access to the unchecked directory in order to upload their packages, they also have that access -to the reject directory in order to remove their bad uploads -or to move some files back in the unchecked directory. But +to the reject directory in order to remove their bad uploads +or to move some files back in the unchecked directory. But all the other directories are only writable by the ftpmasters, that is why you can not remove an upload once it has been accepted. Delayed incoming

-The unchecked directory has a special DELAYED +The unchecked directory has a special DELAYED subdirectory. It is itself subdivised in nine directories -called 1-day to 9-day. Packages which are uploaded in +called 1-day to 9-day. Packages which are uploaded in one of those directories will be moved in the real unchecked directory after the corresponding number of days. This is done by a script that is run each day and which moves the packages between the directories. Those which are in "1-day" are -installed in unchecked while the others are moved in the -adjacent directory (for example, a package in 5-day will -be moved in 4-day). This feature is particularly useful +installed in unchecked while the others are moved in the +adjacent directory (for example, a package in 5-day will +be moved in 4-day). This feature is particularly useful for people who are doing non-maintainer uploads. Instead of waiting before uploading a NMU, it is uploaded as soon as it is -ready but in one of those DELAYED/x-day directories. +ready but in one of those DELAYED/x-day directories. That leaves the corresponding number of days to the maintainer in order to react and upload himself another fix if he is not completely satisfied with the NMU. Alternatively he can remove the NMU by himself.

The use of that delayed feature can be simplified with a bit -of integration with your upload tool, the following addition to -the dupload configuration file should be -considered. -

+of integration with your upload tool. For instance, if you use +dupload (see ), you can add this +snippet to your configuration file: $delay = ($ENV{DELAY} || 7); $cfg{'delayed'} = { - fqdn => "ftp-master.debian.org", + fqdn => "&ftp-master-host;", login => "yourdebianlogin", incoming => "/org/ftp.debian.org/incoming/DELAYED/$delay-day/", visibleuser => "yourdebianlogin", @@ -959,9 +958,8 @@ $cfg{'delayed'} = { method => "scpb" }; -

-dupload can now be used to easily upload a package -in one of the delayed directories : +Once you've made that change, dupload can be used to +easily upload a package in one of the delayed directories: DELAY=5 dupload --to delayed <changes-file> @@ -1002,7 +1000,7 @@ the grep-excuses program part of the devscripts package. It can be easily put in a crontab to keep someone informed of the progression of his packages in testing.

-The update_excuses file does not always give the precise reason +The update_excuses file does not always give the precise reason why the package is refused, one may have to find it by himself by looking what would break with the inclusion of the package. The gives some more information @@ -1019,16 +1017,17 @@ contacted, and he will force the inclusion of the packages. On the web

Each package has several dedicated web pages that contains many -informations. First http://&packages-host;/<package> -will let you discover a presentation of each version of the package -available in the various distributions. It includes its description, -the dependencies and some links to download the package. +informations. http://&packages-host;/package-name +will display each version of the package +available in the various distributions. The per-version detailed +information includes the package description, +the dependencies and links to download the package.

The bug tracking system sorts the bugs by package, you can watch the bugs of each package at -http://&bugs-host;/<package>. +http://&bugs-host;/package-name. - The madison utility + The madison utility

madison is a command-line utility that is available on both &ftp-master-host; and &non-us-host;. It @@ -1222,7 +1221,7 @@ more information.

Assuming no one else is already working on your prospective package, you must then submit a bug report () against the -pseudo package wnpp +pseudo-package wnpp describing your plan to create a new package, including, but not limiting yourself to, a description of the package, the license of the prospective package and the current URL where it can be downloaded @@ -1322,7 +1321,7 @@ to emit errors (they will start with E). For more information on lintian, see . Downgrade the package to the previous version (if one exists) — this -tests the postrm and prerm scripts. +tests the postrm and prerm scripts. Remove the package, then reinstall it. @@ -1331,7 +1330,7 @@ Remove the package, then reinstall it. Generating the changes file

When a package is uploaded to the Debian FTP archive, it must be -accompanied by a .changes file, which gives directions to the +accompanied by a .changes file, which gives directions to the archive maintainers for its handling. This is usually generated by dpkg-genchanges during the normal package build process.

@@ -1350,8 +1349,8 @@ id="upload-bugfix">.

The first time a version is uploaded which corresponds to a particular upstream version, the original source tar file should be uploaded and -included in the .changes file. Subsequently, this very same -tar file should be used to build the new diffs and .dsc +included in the .changes file. Subsequently, this very same +tar file should be used to build the new diffs and .dsc files, and will not need to be re-uploaded.

By default, dpkg-genchanges and @@ -1363,7 +1362,7 @@ may be modified by using -sa to always include it or

If no original source is included in the upload, the original source tar-file used by dpkg-source when constructing the -.dsc file and diff to be uploaded must be +.dsc file and diff to be uploaded must be byte-for-byte identical with the one already in the archive. @@ -1433,7 +1432,7 @@ fix. Uploading to stable

Uploading to stable means that the package will be placed into the -proposed-updates directory of the Debian archive for further +proposed-updates directory of the Debian archive for further testing before it is actually included in stable.

Extra care should be taken when uploading to stable. Basically, a @@ -1473,17 +1472,17 @@ inclusion. Uploading to ftp-master

To upload a package, you need a personal account on -ftp-master.debian.org, which you should have as an +&ftp-master-host;, which you should have as an official maintainer. If you use scp or rsync -to transfer the files, place them into &us-upload-dir;; +to transfer the files, place them into &us-upload-dir;; if you use anonymous FTP to upload, place them into -/pub/UploadQueue/. Please note that you should transfer +&upload-queue;. Please note that you should transfer the changes file last. Otherwise, your upload may be rejected because the archive maintenance software will parse the changes file and see that not all files have been uploaded. If you don't want to bother with transferring the changes file last, you can simply copy your files to a temporary directory on ftp-master and then move them to -&us-upload-dir;. +&us-upload-dir;.

Note: Do not upload to ftp-master cryptographic packages which belong to contrib or non-free. Uploads of @@ -1491,36 +1490,33 @@ such software should go to non-us (see ). Furthermore packages containing code that is patent-restricted by the United States government can not be uploaded to ftp-master; depending on the case they may still be uploaded to -non-US/non-free (it's in non-free because of distribution issues +non-US/non-free (it's in non-free because of distribution issues and not because of the license of the software). If you can't upload it to ftp-master, then neither can you upload it to the overseas upload queues on chiark or erlangen. 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 packages dupload or -dput useful -when uploading packages. These handy programs are distributed with -defaults for uploading via ftp to ftp-master, -chiark, and erlangen. They can also be configured to -use ssh or rsync. See , and for more information. +You may also find the Debian packages or + useful +when uploading packages. These handy programs help automate the +process of uploading packages into Debian.

-After uploading your package, you can check how the archive maintenance -software will process it by running dinstall on your changes -file: dinstall -n foo.changes +After uploading your package, you can check how the archive +maintenance software will process it by running dinstall +on your changes file: dinstall -n foo.changes. +Note that dput can do this for you automatically. Uploading to non-US (pandora)

As discussed above, export controlled software should not be uploaded to ftp-master. Instead, upload the package to non-us.debian.org, placing the files in -&non-us-upload-dir; (both and can be used also, with the right invocation). By default, +&non-us-upload-dir; (again, both and can do this for you if invocated properly). By default, you can use the same account/password that works on ftp-master. If you use anonymous FTP to upload, place the -files into /pub/UploadQueue/. +files into &upload-queue;.

You can check your upload the same way it's done on ftp-master, with: @@ -1558,7 +1554,7 @@ residents consult a lawyer before doing uploads to non-US. Uploads via chiark

If you have a slow network connection to ftp-master, there are -alternatives. One is to upload files to Incoming via a +alternatives. One is to upload files to Incoming via a upload queue in Europe on chiark. For details connect to .

@@ -1578,12 +1574,12 @@ Another upload queue is available in Germany: just upload the files via anonymous FTP to .

The upload must be a complete Debian upload, as you would put it into -ftp-master's Incoming, i.e., a .changes files -along with the other files mentioned in the .changes. The -queue daemon also checks that the .changes is correctly +ftp-master's Incoming, i.e., a .changes files +along with the other files mentioned in the .changes. The +queue daemon also checks that the .changes is correctly signed with GnuPG or OpenPGP by a Debian developer, so that no bogus files can find their way to ftp-master via this queue. Please also make sure that -the Maintainer field in the .changes contains +the Maintainer field in the .changes contains your e-mail address. The address found there is used for all replies, just as on ftp-master.

@@ -1622,7 +1618,7 @@ the ``debian-changes'' lists. This is now done automatically by the archive maintenance software when it runs (usually once a day). You just need to use a recent dpkg-dev (>= 1.4.1.2). The mail generated by the archive maintenance software will contain the OpenPGP/GnuPG signed -.changes files that you uploaded with your package. +.changes files that you uploaded with your package. Previously, dupload used to send those announcements, so please make sure that you configured your dupload not to send those announcements (check its documentation and look for @@ -1792,7 +1788,7 @@ carefully on your machine (cf. ). Double check that your patch doesn't have any unexpected side effects. Make sure your patch is as small and as non-disruptive as it can be. -Upload your package to incoming in DELAYED/7-day (cf. +Upload your package to incoming in DELAYED/7-day (cf. ), send the final patch to the maintainer via the BTS, and explain him that he has 7 days to react if he wants to cancel the NMU. @@ -2002,7 +1998,7 @@ Manual">. Setting your architecture to ``i386'' is usually incorrect. Make sure your source package is correct. Do dpkg-source -x package.dsc to make sure your source package unpacks properly. Then, in there, try building your package from scratch with -dpkg-buildpackage. +dpkg-buildpackage. Make sure you don't ship your source package with the debian/files or debian/substvars files. @@ -2260,10 +2256,10 @@ the actual code has evolved into another package (e.g. libfoo12 was removed because libfoo13 supersedes it) or closed if the software is simply no more part of Debian. - Removing packages from Incoming + Removing packages from Incoming

-In the past, it was possible to remove packages from incoming. -With the introduction of the New Incoming system this is no longer +In the past, it was possible to remove packages from incoming. +However, 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 @@ -2298,7 +2294,7 @@ of the message (no, don't use CC:, because that way the message's subject won't indicate the bug number).

If the package is especially crucial to Debian, you should instead submit -a bug against wnpp and title it RFA: package -- +a bug against wnpp and title it RFA: package -- short description and set its severity to important. RFA stands for Request For Adoption. Definitely copy the message to debian-devel in this case, as described @@ -2348,10 +2344,10 @@ If you want to be a good maintainer, you should periodically check the for your packages. The BTS contains all the open bugs against your packages. You can check them by browsing this page: -http://&bugs-host;/yourlogin@debian.org. +http://&bugs-host;/yourlogin@debian.org.

Maintainers interact with the BTS via email addresses at -bugs.debian.org. Documentation on available commands can be +&bugs-host;. Documentation on available commands can be found at , or, if you have installed the doc-debian package, you can look at the local files &file-bts-docs;. @@ -2433,7 +2429,7 @@ one of the most concise and easiest to integrate with the text of the changelog.

If you want to close bugs the old fashioned, manual way, it is usually -sufficient to mail the .changes file to +sufficient to mail the .changes file to XXX-done@bugs.debian.org, where XXX is your bug number. @@ -2524,7 +2520,7 @@ From time to time you may want to check what has been going on with the bug reports that you submitted. Take this opportunity to close those that you can't reproduce anymore. To find out all the bugs you submitted, you just have to visit -http://&bugs-host;/your-email@your-isp.com. +http://&bugs-host;/<your-email>@your-isp.com. Reporting lots of bugs at once

@@ -2584,14 +2580,16 @@ way of cooperating between a set of related packages, or you may simply remind someone that a new upstream version is available and that you need it.

-Whatever the reason, it is a pain to lookup the email address of the -maintainer of the package that you are interested in. Fortunately, you -can use a simple email alias : <package>@&packages-host;. -<package> can be the name of a source or a binary package. +Looking up the email address of the maintainer for the package can be +distracting. Fortunately, there is a simple email alias, +<package>@&packages-host;, which provides a way to +email the maintainer, whatever their individual email address (or +addresses) may be. Replace <package> with the name of +a source or a binary package.

You may also be interested by contacting the persons who are subscribed to a given source package via . -You can do so by using the <package>@&pts-host; +You can do so by using the <package-name>@&pts-host; email address. @@ -2636,12 +2634,12 @@ By uploading a sponsored package to Debian, you are certifying that the package meets minimum Debian standards. That implies that you must build and test the package on your own system before uploading.

-You can not simply upload a binary .deb from the sponsoree. In +You can not simply upload a binary .deb from the sponsoree. In theory, you should only ask only for the diff file, and the location of the original source tarball, and then you should download the source and apply the diff yourself. In practice, you may want to use the source package built by your sponsoree. In that case you have to check that he hasn't -altered the upstream files in the .orig.tar.gz file that he's +altered the upstream files in the .orig.tar.gz file that he's providing.

Do not be afraid to write the sponsoree back and point out changes @@ -2651,11 +2649,11 @@ means being a mentor.

Once the package meets Debian standards, build the package with dpkg-buildpackage -us -uc and sign it -with debsign -m your@email.com changes file +with debsign -m <your-email-addr> <changes-file> before uploading it to the incoming directory.

-The Maintainer field of the control file and the -changelog should list the person who did the packaging, i.e. the +The Maintainer field of the control file and the +changelog should list the person who did the packaging, i.e. the sponsoree. The sponsoree will therefore get all the BTS mail about the package.

@@ -2697,7 +2695,7 @@ endorse any particular tool to the exclusion of a competing tool. Most of the descriptions of these packages come from the actual package descriptions themselves. Further information can be found in the package documentation itself. You can also see more info with the -command apt-cache show package_name. +command apt-cache show <package-name>. @@ -2829,7 +2827,7 @@ The dput package and script does much the same thing as dupload, but in a different way. It has some features over dupload, such as the ability to check the GnuPG signature and checksums before uploading, and the -possibility of running dinstall in dry-run mode after the +possibility of running dinstall in dry-run mode after the upload. @@ -2885,7 +2883,7 @@ finalizing a version and listing the package's current bugs. debget is a package containing a convenient script which can be helpful in downloading files from the Debian archive. You can use it to download source packages, for instance (although -apt-get source package does pretty much the same +apt-get source <package-name> does pretty much the same thing).