Bug#1127616: developers-reference: should document using git-debpush to upload

Sean Whitton <[email protected]> Tue, 10 Feb 2026 14:52:12 +0000
Newsgroups	gmane.linux.debian.devel.policy
Message-ID	<87pl6czm5f.fsf__40945.357426402$1770735231$gmane$org@zephyr.silentflame.com>
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 (application/pgp-signature, 869 B)