Add Ubuntu Policy Manual article

docs/how-ubuntu-is-made/index.md

@@ -12,6 +12,16 @@ All about the Ubuntu Community, its support structures, and communication channe
 /community/index
 ```
 
+## The Ubuntu Policy Manual
+
+Policy requirements for the Ubuntu distribution.
+
+```{toctree}
+:maxdepth: 3
+
+ubuntu-policy/index
+```
+
 ## Project governance
 
 How the project is governed. This sets out the expectations for contributors and maintainers alike.

docs/how-ubuntu-is-made/ubuntu-policy/1-about-this-manual.rst

@@ -0,0 +1,130 @@
+.. _chapter-1-about-this-manual:
+
+Chapter 1 - About this manual
+-----------------------------
+
+1.1 Scope
+~~~~~~~~~
+
+This manual describes the policy requirements for the Ubuntu distribution. This
+includes the structure and contents of the Ubuntu archive and several design
+issues of the operating system, as well as technical requirements that each
+package must satisfy to be included in the distribution.
+
+This manual also describes Ubuntu policy as it relates to creating Ubuntu
+packages. It is not a tutorial on how to build packages, nor is it exhaustive
+where it comes to describing the behavior of the packaging system. Instead,
+this manual attempts to define the interface to the package management system
+that the developers have to be conversant with. [#f1]_
+
+The footnotes present in this manual are merely informative, and are not part
+of Ubuntu policy itself.
+
+The appendices to this manual are not necessarily normative, either. Please see
+:ref:`Appendix A <appendix-a>` for more information.
+
+In the normative part of this manual, the words *must*, *should* and *may*, and
+the adjectives *required*, *recommended* and *optional*, are used to
+distinguish the significance of the various guidelines in this policy document.
+Packages that do not conform to the guidelines denoted by must (or required)
+will generally not be considered acceptable for the Ubuntu distribution.
+Non-conformance with guidelines denoted by *should* (or *recommended*) will
+generally be considered a bug, but will not necessarily render a package
+unsuitable for distribution. Guidelines denoted by *may* (or *optional*) are
+truly optional and adherence is left to the maintainer's discretion.
+
+These classifications are roughly equivalent to the bug severities *serious*
+(for *must* or *required* directive violations), *minor*, *normal* or
+*important* (for *should* or *recommended* directive violations) and *wishlist*
+(for optional items). [#f2]_
+
+Much of the information presented in this manual will be useful even when
+building a package which is to be distributed in some other way or is intended
+for local use only.
+
+The Ubuntu distribution differs from its parent Debian distribution in a
+number of significant ways. In this document, these are marked with the tag
+*Ubuntu*:.
+
+----
+
+1.2 New versions of this document
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Historically, this manual has been distributed via the Ubuntu package
+ubuntu-policy (packages.ubuntu.com http://packages.ubuntu.com/ubuntu-policy).
+Now, the policy is hosted on the Ubuntu Project Docs under the
+:ref:`ubuntu-policy`.
+
+----
+
+1.3 Authors and Maintainers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Originally called "Debian GNU/Linux Policy Manual", this manual was initially
+written in 1996 by Ian Jackson. It was revised on November 27th, 1996 by David
+A. Morris. Christian Schwarz added new sections on March 15th, 1997, and
+reworked/restructured it in April-July 1997. Christoph Lameter contributed the
+"Web Standard". Julian Gilbey largely restructured it in 2001.
+
+The Ubuntu branch of this manual is maintained by the `ubuntu-devel mailing
+list <mailto:ubuntu-devel@lists.ubuntu.com>`_. In 2026 Simon Johnsson reduced
+the branch to the differences between Debian and Ubuntu, and moved it to the
+Ubuntu Project Docs.
+
+Since September 1998, the responsibility for the contents of the Debian
+version of this document lies on the `debian-policy mailing list
+<mailto:debian-policy@lists.debian.org>`_. Proposals are
+discussed there and inserted into policy after a certain consensus is
+established.
+
+----
+
+.. _ubuntu-policy-related-documents:
+
+1.4 Related documents
+~~~~~~~~~~~~~~~~~~~~~
+
+(*Shared with Debian, see:* `Debian Policy Manual, Section 1.4
+<https://www.debian.org/doc/debian-policy/ch-scope.html#related-documents>`_)
+
+----
+
+1.5 Definitions
+~~~~~~~~~~~~~~~
+
+(*Shared with Debian, see:* `Debian Policy Manual, Section 1.5
+<https://www.debian.org/doc/debian-policy/ch-scope.html#definitions>`_)
+
+----
+
+:ref:`← (Ubuntu Policy Manual) <ubuntu-policy>` | :ref:`(Chapter 2 - The Ubuntu Archive) → <chapter-2-ubuntu-archive>`
+
+----
+
+.. [#f1]
+   Informally, the criteria used for inclusion is that the material meet one of
+   the following requirements:
+
+    :Standard interfaces:
+
+        The material presented represents an interface to the packaging system
+        that is mandated for use,     and is used by, a significant number of
+        packages, and therefore should not be changed without peer review.
+        Package maintainers can then rely on this interfaces not changing, and
+        the package management software authors need to ensure compatibility
+        with these interface definitions. (Control file and changelog file
+        formats are examples.) 
+
+    :Chosen Convention:
+
+        If there are a number of technically viable choices that can be made,
+        but one needs to select one of these options for inter-operability. The
+        version number format is one example.
+
+    Please note that these are not mutually exclusive; selected conventions
+    often become parts of standard interfaces.
+.. [#f2]
+   Compare RFC 2119. Note, however, that these words are used in a different
+   way in this document.
+

docs/how-ubuntu-is-made/ubuntu-policy/10-files.rst

@@ -0,0 +1,168 @@
+.. _chapter-10-files:
+
+Chapter 10 - Files
+------------------
+
+10.1 Binaries
+~~~~~~~~~~~~~
+
+(*Shared with Debian, see:* `Debian Policy Manual, Section 10.1
+<https://www.debian.org/doc/debian-policy/ch-files.html#binaries>`_)
+
+----
+
+.. _ubuntu-policy-libraries:
+
+10.2 Libraries
+~~~~~~~~~~~~~~
+
+(*Shared with Debian, see:* `Debian Policy Manual, Section 10.2
+<https://www.debian.org/doc/debian-policy/ch-files.html#libraries>`_)
+
+----
+
+10.3 Shared libraries
+~~~~~~~~~~~~~~~~~~~~~
+
+This section has moved to `Shared libraries, Chapter 8
+<chapter-8-shared-libraries>`_.
+
+----
+
+10.4 Scripts
+~~~~~~~~~~~~
+
+(*Shared with Debian, see:* `Debian Policy Manual, Section 10.4
+<https://www.debian.org/doc/debian-policy/ch-files.html#scripts>`_)
+
+----
+
+10.5 Symbolic links
+~~~~~~~~~~~~~~~~~~~
+
+(*Shared with Debian, see:* `Debian Policy Manual, Section 10.5
+<https://www.debian.org/doc/debian-policy/ch-files.html#symbolic-links>`_)
+
+----
+
+10.6 Device files
+~~~~~~~~~~~~~~~~~
+
+(*Modifies*: `Debian Policy Manual, Section 10.6
+<https://www.debian.org/doc/debian-policy/ch-files.html#device-files>`_)
+
+Packages must not include device files in the package file tree.
+
+If a package needs any special device files that are not included in the base
+system, it must call MAKEDEV in the postinst script, after notifying the
+user [#f72]_.
+
+Packages must not remove any device files in the postrm or any other script.
+This is left to the system administrator.
+
+Ubuntu uses the serial devices :file:`/dev/ttyS*`. Programs using the old
+:file:`/dev/cu*` devices should be changed to use :file:`/dev/ttyS*`.
+
+----
+
+10.7 Configuration files
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+    **Editor's note**: This section is considerably similar to the Debian
+    policy. Review is suggested.
+
+10.7.1 Definitions
+^^^^^^^^^^^^^^^^^^
+
+(*Shared with Debian, see:* `Debian Policy Manual, Section 10.7.1
+<https://www.debian.org/doc/debian-policy/ch-files.html#configuration-files-definitions>`_)
+
+10.7.2 Location
+^^^^^^^^^^^^^^^
+
+(*Shared with Debian, see:* `Debian Policy Manual, Section 10.7.2
+<https://www.debian.org/doc/debian-policy/ch-files.html#configuration-files-location>`_)
+
+10.7.3 Behavior
+^^^^^^^^^^^^^^^
+
+(*Shared with Debian, see:* `Debian Policy Manual, Section 10.7.3
+<https://www.debian.org/doc/debian-policy/ch-files.html#configuration-files-behavior>`_)
+
+10.7.4 Sharing configuration files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+(*Modifies*: `Debian Policy Manual, Section 10.7.4
+<https://www.debian.org/doc/debian-policy/ch-files.html#sharing-configuration-files)>`_)
+
+Packages which specify the same file as a ``conffile`` must be tagged as
+*conflicting* with each other. (This is an instance of the general rule about
+not sharing files. Note that neither alternatives nor diversions are likely to
+be appropriate in this case; in particular, :pkg:`dpkg` does not handle
+diverted conffiles well.)
+
+The maintainer scripts must not alter a conffile of any package, including the
+one the scripts belong to.
+
+If two or more packages use the same configuration file and it is reasonable
+for both to be installed at the same time, one of these packages must be
+defined as *owner* of the configuration file, i.e., it will be the package
+which handles that file as a configuration file. Other packages that use the
+configuration file must depend on the owning package if they require the
+configuration file to operate. If the other package will use the configuration
+file if present, but is capable of operating without it, no dependency need be
+declared.
+
+If it is desirable for two or more related packages to share a configuration
+file *and* for all of the related packages to be able to modify that
+configuration file, then the following should be done:
+
+One of the related packages (the "owning" package) will manage the
+configuration file with maintainer scripts as described in the previous
+section.
+
+The owning package should also provide a program that the other packages may
+use to modify the configuration file.
+
+The related packages must use the provided program to make any desired
+modifications to the configuration file. They should either depend on the core
+package to guarantee that the configuration modifier program is available or
+accept gracefully that they cannot modify the configuration file if it is not.
+(This is in addition to the fact that the configuration file may not even be
+present in the latter scenario.)
+
+Sometimes it's appropriate to create a new package which provides the basic
+infrastructure for the other packages and which manages the shared
+configuration files. (The :pkg:`sgml-base` package is a good example.)
+
+10.7.5 User configuration files ("dotfiles")
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+(*Shared with Debian, see:* `Debian Policy Manual, Section 10.7.5
+<https://www.debian.org/doc/debian-policy/ch-files.html#user-configuration-files-dotfiles>`_)
+
+----
+
+10.8 Log files
+~~~~~~~~~~~~~~
+
+(*Shared with Debian, see:* `Debian Policy Manual, Section 10.8
+<https://www.debian.org/doc/debian-policy/ch-files.html#log-files>`_)
+
+----
+
+10.9 Permissions and owners
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+(*Shared with Debian, see:* `Debian Policy Manual, Section 10.9
+<https://www.debian.org/doc/debian-policy/ch-files.html#permissions-and-owners>`_)
+
+----
+
+:ref:`← (Chapter 9 - The Operating System) <chapter-9-the-operating-system>` | :ref:`(Chapter 11 - Customized programs) → <chapter-11-customized-programs>`
+
+----
+
+.. [#f72]
+   This notification could be done via a (low-priority) debconf message, or an
+   echo (printf) statement.