Package: developers-reference Severity: important X-debbugs-cc: [email protected], [email protected]
I made the following change to dev-ref, but it was reverted. So with this bug I request review from the Developer's Reference maintainers. I didn't think there is anything controversial about this, but please let me know what you think needs changing. Brief rationale: This section of dev-ref is for newcomers. So I changed it to recommend git-debpush, because that is the thing they are most likely to want to use. --8<---------------cut here---------------start------------->8--- diff --git a/source/pkgs.rst b/source/pkgs.rst index 41d0147..65b6252 100644 --- a/source/pkgs.rst +++ b/source/pkgs.rst @@ -347,61 +347,90 @@ Uploading a package Source and binary uploads -------------------------------------------------------------------------------------------------------------------------------- -Each upload to Debian consists of a signed ``.changes`` file describing -the requested change to the archive, plus the source and binary package -files that are referenced by the ``.changes`` file. - -If possible, the version of a package that is uploaded should be a -source-only changes file. -These are typically named ``*_source.changes``, and reference the source -package, but no binary ``.deb`` or ``.udeb`` packages. -All of the corresponding architecture-dependent and architecture-independent -binary packages, for all architectures, will be built automatically by -the build daemons in a controlled and predictable environment +The Debian Archive distributes both source code and the binary packages built +from that source code. In the usual case, you supply the source code and the +build daemons supply the binary packages, and the Debian Archive software is +responsible for associating them with each other based on packaging metadata. +The act of supplying new source code in this way is called a *source-only +upload*. + +The build daemons then perform corresponding *binary-only uploads*. The +advantage of this is that all of the corresponding architecture-dependent and +architecture-independent binary packages, for all architectures, are built +automatically by the build daemons in a controlled and predictable environment (see :ref:`wanna-build` for more details). -However, there are several situations where this is not possible. - -The first upload of a new source package (see :ref:`newpackage`) -must include binary packages, so that they can be reviewed by the -archive administrators before they are added to Debian. - -If new binary packages are added to an existing source package, then the -first upload that lists the new binary packages in ``debian/control`` -must include binary packages, again so that they can be reviewed by the -archive administrators before they are added to Debian. -It is preferred for these uploads to be done via the ``experimental`` -suite. - -Uploads that will be held for review in other queues, such as packages -being added to the ``*-backports`` suites, might also require inclusion -of binary packages. - -The build daemons will automatically attempt to build any ``main`` or -``contrib`` package for which the build-dependencies are available. -Packages in ``non-free`` and ``non-free-firmware`` will not be built by -the build daemons unless the package has been marked as suitable for -auto-building -(see :ref:`non-free-buildd`). - -The build daemons only install build-dependencies from the ``main`` -archive area. -This means that if a source package has build-dependencies that are -in the ``contrib``, ``non-free`` or ``non-free-firmware`` archive areas, -then uploads of that package need to include prebuilt binary packages -for every architecture that will be supported. -By definition this can only be the case for source packages that are -themselves in the ``contrib``, ``non-free`` or ``non-free-firmware`` -archive areas. - -Bootstrapping a new architecture, or a new version of a package with -circular dependencies (such as a self-hosting compiler), will sometimes -also require an upload that includes binary packages. + +To perform a source-only upload, use the ``git debpush`` program. Usually you +just type ``git debpush``, but sometimes you need to pass additional options. +You don't need to know in advance when additional options are required, +because ``git debpush`` will error out in that case. We'll avoid repeating +the details of when additional options may be required here: see the +(relatively short and sweet) git-debpush(1) manpage if and when this comes up +for you. See also https://wiki.debian.org/tag2upload\ . + +``git debpush`` covers the vast majority of source-only uploads that Debian +package maintainers perform. However, there are some cases in which a +source-only upload is possible but ``git debpush`` cannot be used: when doing +an NMU (see :ref:`nmu`); when the package is not maintained on Salsa (see +:ref:`salsa-debian-org`) at all; or when the package uses a Git workflow that +``git debpush`` doesn't yet know how to handle. A notable example of the +latter is teams who use monorepos to store multiple source packages in one Git +repository. + +There are also cases where a source-only upload isn't possible at all, because +you need to upload both source code and binary packages at the same time. +This happens in the following circumstances in which your upload will be held +in a queue for manual approval by the archive administrators before heading +into the Debian Archive proper: + +- When uploading a new source package for the very first time (see + :ref:`newpackage`). +- When adding new binary packages to an existing source package: the first + upload that lists the new binary packages in ``debian/control`` must include + binary packages. It is preferred for these uploads to be done via the + ``experimental`` suite. +- Packages being added to a ``*-backports`` suite for the first time. + +Note that not all Debian Archive manual approval queues requires uploading +binaries -- proposed updates to Debian stable (see :ref:`upload-stable`), for +example, do not. + +There are also cases in which you must perform binary-only uploads subsequent +to your ``git debpush``. The build daemons will automatically attempt to +build any ``main`` or ``contrib`` package for which the build-dependencies are +available. Packages in ``non-free`` and ``non-free-firmware`` will not be +built by the build daemons unless the package has been marked as suitable for +auto-building (see :ref:`non-free-buildd`). In that case, you'll need to +upload the binary packages yourself as part of a binary-only upload. + +The build daemons only install build-dependencies from the ``main`` archive +area. This means that if a source package has build-dependencies that are in +the ``contrib``, ``non-free`` or ``non-free-firmware`` archive areas, then +you'll need to perform binary-only uploads of prebuilt binary packages for +every architecture that will be supported. By definition this can only be the +case for source packages that are themselves in the ``contrib``, ``non-free`` +or ``non-free-firmware`` archive areas. + +Bootstrapping a new architecture, or a new version of a package with circular +dependencies (such as a self-hosting compiler), will sometimes also require +making binary-only uploads. .. _upload-ftp-master: Uploading to ``ftp-master`` -------------------------------------------------------------------------------------------------------------------------------- +When you need to make a source-only upload without ``git debpush``; upload +source and binary packages at the same time for NEW; or make a binary-only +upload, you will need to upload to ``ftp-master`` directly. Each upload to +``ftp-master`` consists of a signed ``.changes`` file describing the +ubmission, plus the source and binary package files that are referenced by the +``.changes`` file. + +A source-only changes file makes for a source-only upload. These are +typically named ``*_source.changes``, and reference the source package, but no +binary ``.deb`` or ``.udeb`` packages. + To upload a package, you should upload the files (including the signed changes and dsc file) with anonymous ftp to ``ftp.upload.debian.org`` in the directory --8<---------------cut here---------------end--------------->8--- -- Sean Whitton
signature.asc
Description: PGP signature
