Initial Packaging guide move

docs/.custom_wordlist.txt

@@ -25,12 +25,15 @@ backend
 backends
 backgrounding
 backport
+backported
 backporting
 backports
 Bileto
+blocklist
 BOF
 BOFs
 bootable
+bootloader
 bootloaders
 bugpatterns
 Bugpatterns
@@ -53,21 +56,29 @@ conformant
 cjk
 cron
 crontab
+crossbuild
 cryptographic
 cryptographically
 CVE
 CVEs
 datacenter
 debdiff
+debhelper
 debian
 Debian
+DebSrc
+deprioritized
 DEP
 DEPs
 dev
+DevOps
 devs
 devel
+dh
 DIF
 distro
+downstreamed
+downstreams
 dvipng
 edubuntu
 EFI
@@ -76,7 +87,9 @@ empathic
 EoSS
 equalizing
 executables
+FHS
 filesystem
+filesystems
 flavour
 Flavour
 flavours
@@ -117,7 +130,9 @@ Kylin
 lang
 Langpack
 latexmk
+launchpadlib
 LGPL
+Libera
 licence
 lifecycle
 lintian
@@ -126,16 +141,15 @@ lockfile
 logfile
 Lubuntu
 macOS
+Maintainer's
 manpage
 Matic
 meetingology
 mentorship
 metapackage
-<<<<<<< more-glossary
+microrelease
 microreleases
-=======
 metapackages
->>>>>>> main
 mir
 MIR
 MIRs
@@ -155,6 +169,7 @@ organized
 otf
 packageset
 PDFs
+PID
 plantuml
 powerpc
 PPA
@@ -170,16 +185,22 @@ rst
 rulebook
 RULEs
 SCM
+schroots
 SLO
 SLOs
 SONAME
 SRU
 SRUs
+subdirectory
+subiquity
 submitters
 submitter's
+Tahr
 Tegra
+testbed
 tex
 texlive
+theming
 TOC
 toctree
 TODOs
@@ -191,7 +212,18 @@ ubuntu
 Ubuntu
 UDD
 UEFI
+UIF
 un
+unapplied
+Unapply
+unapply
+unpatched
+upgrader
+upstreamed
+upstreaming
+upstreams
+Unshareable
+unshareable
 uploader
 uploaders
 utils
@@ -206,6 +238,7 @@ WNPP
 wordlist
 workspaces
 Xenial
+Xerus
 xetex
 XFCE
 xindy

docs/conf.py

@@ -85,14 +85,14 @@
 
 # Preview image URL
 #
-# TODO: To customise the preview image, update as needed.
+# TODO: To customize the preview image, update as needed.
 
 ogp_image = "https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg"
 
 
 # Product favicon; shown in bookmarks, browser tabs, etc.
 
-# TODO: To customise the favicon, uncomment and update as needed.
+# TODO: To customize the favicon, uncomment and update as needed.
 
 # html_favicon = '.sphinx/_static/favicon.png'
 
@@ -266,7 +266,6 @@
 
 rst_epilog = """
 .. include:: /reuse/links.txt
-.. include:: /reuse/substitutions.txt
 """
 
 # Feedback button at the top; enabled by default
@@ -343,6 +342,7 @@
         "https://canonical-starter-pack.readthedocs-hosted.com/latest/",
         None,
     ),
+    "sru": ("https://canonical-sru-docs.readthedocs-hosted.com/en/latest", None),
 }
 
 

docs/reference/glossary.md

@@ -503,13 +503,6 @@ distro
     See also:
     * [Linux distribution (Wikipedia)](https://en.wikipedia.org/wiki/Linux_distribution)
 
-DMB
-Developer Membership Board
-    *Work in Progress*
-
-    See also:
-    * [Developer Membership Board (Ubuntu Wiki)](https://wiki.ubuntu.com/DeveloperMembershipBoard)
-
 DNS
 Domain Name System
     *Work in Progress*

docs/reuse/links.txt

@@ -0,0 +1,18 @@
+.. _CanonicalDiscourse: https://discourse.canonical.com
+.. _GitHub: https://github.com/
+.. _GitUbuntuBugs: https://bugs.launchpad.net/git-ubuntu
+.. _Launchpad: https://launchpad.net
+.. _UbuntuDiscourse: https://discourse.ubuntu.com
+
+.. _Edubuntu: https://edubuntu.org/
+.. _Kubuntu: https://kubuntu.org/
+.. _Lubuntu: https://lubuntu.me/
+.. _Ubuntu Budgie: https://ubuntubudgie.org/
+.. _Ubuntu Cinnamon: https://ubuntucinnamon.org/
+.. _Ubuntu Kylin: https://www.ubuntukylin.com/index-en.html
+.. _Ubuntu MATE: https://ubuntu-mate.org/
+.. _Ubuntu Studio: https://ubuntustudio.org/
+.. _Ubuntu Unity: https://ubuntuunity.org/
+.. _Xubuntu: https://xubuntu.org/
+
+.. _DEP3Spec: https://dep-team.pages.debian.net/deps/dep3/

docs/staging.md

@@ -17,4 +17,5 @@ This page (and staging area) will be removed as it becomes unnecessary.
 
 staging/*
 staging/AA/archive-administration
+staging/PG/index
 ```

docs/staging/PG/contributors/bug-fix/build-packages.rst

@@ -0,0 +1,157 @@
+Build packages
+==============
+
+In Ubuntu, packages can be built in several ways, depending on the intended
+artifacts. We cover the following types of builds:
+
+* Source and binary (using ``sbuild`` for a clean environment)
+* Binary-only (using ``sbuild`` for a clean environment)
+* Source-only (using ``debuild``)
+* Binary-only (using ``debuild`` and installed build dependencies)
+
+(Many other backends are available, including an ``schroot``-based backend.)
+
+Only source uploads are permitted to PPAs or the archive. That
+being said, it is best practice to perform a local build and iron out any
+potential issues prior to uploading it to any archive.
+
+
+Prerequisites
+-------------
+
+.. code-block:: text
+
+    $ sudo apt install sbuild debhelper ubuntu-dev-tools piuparts
+
+All of the following sections assume you have already fetched the packaging
+and are in the same directory as :file:`debian/`.
+
+
+``sbuild``-based builds
+-----------------------
+
+This is the standard way of building a package for Ubuntu. All of the Debian
+and Ubuntu infrastructure use :manpage:`sbuild(1)`, so it is beneficial to
+learn how to use it. For more information on setting up :manpage:`sbuild(1)`,
+refer to the links in the Resources section.
+
+To do a binary-only build of a package using ``sbuild``, run:
+
+.. code-block:: text
+
+    $ sbuild -c <RELEASE>-<ARCH>[-shm]
+
+.. note::
+
+    It is possible to use ``-d`` instead of ``-c``, but that causes the produced
+    files to contain the entire chroot name (``<RELEASE>-<ARCH>[-shm]``) instead
+    of just ``<RELEASE>``. An example chroot name is ``noble-amd64-shm``.
+
+To explicitly run Lintian following the build:
+
+.. code-block:: text
+
+    $ sbuild -c <RELEASE>-<ARCH>[-shm] --run-lintian [--lintian-opts="-EvIiL +pedantic"]
+
+To build a package without running :manpage:`dh_clean(1)`, run:
+
+.. code-block:: text
+
+    $ sbuild -c <RELEASE>-<ARCH>[-shm] --no-clean-source
+
+To build both a binary *and* a source package with one ``sbuild`` run:
+
+.. code-block:: text
+
+    $ sbuild -c <RELEASE>-<ARCH>[-shm] -s
+
+.. note::
+
+    Launchpad rejects uploads that contains both binaries and sources.
+    However, this is required for uploads to the Debian NEW queue. That being
+    said, uploads to Debian with binaries `do not migrate to Testing <https://lists.debian.org/debian-devel-announce/2019/07/msg00002.html>`_.
+
+Here is a complete, working example of running the ``autopkgtest`` following the build:
+
+.. code-block:: text
+
+    $ sbuild -c noble-amd64-shm --run-autopkgtest \
+      --autopkgtest-virt-server=qemu \
+      --autopkgtest-virt-server-opt="/path/to/autopkgtest-noble-amd64.img" \
+      --autopkgtest-opt="--apt-pocket=proposed=src:qt6-base" \
+      --autopkgtest-opt="-U" --autopkgtest-opt="--ram-size=12000" \
+      --autopkgtest-opt="--setup-commands='apt-get -y install aptitude \
+        && aptitude -t noble-proposed -y install qt6-base-dev=6.8.1+dfsg-0ubuntu1'"
+
+
+Building with ``debuild``
+-------------------------
+
+:manpage:`debuild(1)` (short for :manpage:`dpkg-buildpackage(1)`) is
+another tool used to build Debian packages. It is part of the
+:manpage:`debhelper(7)` package and written in Perl.
+
+Ubuntu maintain its own version the ``debhelper`` package. Therefore,
+packages built on Debian may be slightly different than packages built on
+Ubuntu.
+
+
+Source-only builds
+~~~~~~~~~~~~~~~~~~
+
+To build a source package *without* including the upstream tarball, run:
+
+.. code-block:: text
+
+    $ debuild -S -d
+
+To build a source package *with* the upstream tarball, run:
+
+.. code-block:: text
+
+    $ debuild -S -d -sa
+
+To build a source package without running Lintian, run:
+
+.. code-block:: text
+
+    $ debuild --no-lintian -S -d
+
+.. note::
+
+    The ``--no-lintian`` flag only works in this case if it is first.
+
+To build a source package without running :manpage:`dh_clean(1)`, run:
+
+.. code-block:: text
+
+    $ debuild -S -d -nc
+
+.. note::
+
+    This tends to fix failures regarding missing build dependencies.
+
+To build a source package without a cryptographic signature (not recommended), run:
+
+.. code-block:: text
+
+    $ debuild -S -d -us -uc
+
+
+Local binary-only builds
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is really only useful for packages you need to test locally or
+packages with minimal build dependencies. Otherwise use :manpage:`sbuild(1)`.
+
+To do a binary-only build of a package, run:
+
+.. code-block:: text
+
+    $ debuild -b
+
+
+Resources
+---------
+
+* `Chapter 6. Building the package (Debian New Maintainers' Guide) <https://www.debian.org/doc/manuals/maint-guide/build.html>`_