XPost: linux.debian.devel, linux.debian.policy   
   From: spwhitton@spwhitton.name   
      
   Package: developers-reference   
   Severity: important   
   X-debbugs-cc: debian-devel@lists.debian.org, git-debpush@packages.debian.org   
      
   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   
      
   [continued in next message]   
      
   --- SoupGate-Win32 v1.05   
    * Origin: you cannot sedate... all the things you hate (1:229/2)