49 | {% endblock right_sidebar %}
50 |
--------------------------------------------------------------------------------
/snap/local/src/common.py:
--------------------------------------------------------------------------------
1 | import os
2 | import subprocess
3 |
4 |
5 | def GetSnapPath() -> str:
6 | return os.environ["SNAP"]
7 |
8 |
9 | def GetVersion() -> str:
10 | path = os.path.join(GetSnapPath(), "usr", "share",
11 | "ubuntu-packaging-guide", "meta", "VERSION")
12 | with open(path, 'r') as file:
13 | return file.readline().rstrip()
14 |
15 |
16 | def GetCommitHash() -> str:
17 | path = os.path.join(GetSnapPath(), "usr", "share",
18 | "ubuntu-packaging-guide", "meta", "COMMIT-HASH")
19 | with open(path, 'r') as file:
20 | return file.readline().rstrip()
21 |
22 |
23 | def SnapctlGet(key: str, defaultValue: str) -> str:
24 | value = subprocess.check_output(["snapctl", "get", key], text=True).strip()
25 |
26 | if value == "":
27 | return defaultValue
28 |
29 | return value
30 |
31 |
32 | def GetHttpAddress() -> str:
33 | return SnapctlGet("http.address", "localhost")
34 |
35 |
36 | def GetHttpPort() -> int:
37 | return int(SnapctlGet("http.port", "9000"))
38 |
39 |
40 | def GetBasePath() -> str:
41 | return os.path.join(GetSnapPath(), "usr", "share",
42 | "ubuntu-packaging-guide", "www")
43 |
44 |
45 | def GetDeamonStatus() -> str:
46 | return subprocess.check_output("snapctl services "
47 | "| grep 'ubuntu-packaging-guide.deamon' "
48 | "| awk '{print $3}'",
49 | shell=True, text=True).strip()
50 |
--------------------------------------------------------------------------------
/docs/reuse/snippets/quilt/configure.bash:
--------------------------------------------------------------------------------
1 | cat <<'EOF' > ~/.quiltrc
2 | #!/usr/bin/env bash
3 | set -euo pipefail
4 |
5 | # find the root of a debian source tree:
6 | SourcePackageRoot="${PWD}"
7 | while [ ! -s "$SourcePackageRoot/debian/source/format" ]
8 | do
9 | if [ "${SourcePackageRoot}" = '/' ]
10 | then
11 | echo -e '\033[1;33mWARNING\033[0m: You are not in a debian source tree!'
12 | exit 0
13 | fi
14 |
15 | SourcePackageRoot="$(readlink --canonicalize-existing "${SourcePackageRoot}/..")"
16 | done
17 |
18 | if ! grep --silent --fixed-strings '3.0 (quilt)' \
19 | "${SourcePackageRoot}/debian/source/format"
20 | then
21 | echo -e '\033[1;33mWARNING\033[0m: This source package does \033[1mNOT\033[0m use the 3.0 (quilt) format. The corresponding defaults defined in ~/.quiltrc do not get applied.'
22 | exit 0
23 | fi
24 |
25 | # tell quilt where to find patches for a 3.0 (quilt) source package
26 | : "${QUILT_PATCHES:="${SourcePackageRoot}/debian/patches"}"
27 |
28 | # create the quilt control files directory at the root of the source package
29 | : "${QUILT_PC:="${SourcePackageRoot}/.pc"}"
30 |
31 | # default options for the patch(1) tool
32 | : "${QUILT_PATCH_OPTS:="--reject-format=unified"}"
33 |
34 | # how quilt output should be colored
35 | : "${QUILT_COLORS:="diff_hdr=1;32:diff_add=1;34:diff_rem=1;31:diff_hunk=1;33:diff_ctx=35:diff_cctx=33"}"
36 |
37 | # set default arguments for quilt commands:
38 | : "${QUILT_DIFF_ARGS:="-p ab --no-timestamps --no-index --color=auto"}"
39 | : "${QUILT_PATCHES_ARGS:="--color=auto"}"
40 | : "${QUILT_PUSH_ARGS:="--color=auto"}"
41 | : "${QUILT_REFRESH_ARGS:="-p ab --no-timestamps --no-index"}"
42 | : "${QUILT_SERIES_ARGS:="--color=auto"}"
43 | EOF
44 |
--------------------------------------------------------------------------------
/docs/reference/architectures.rst:
--------------------------------------------------------------------------------
1 | Supported architectures
2 | =======================
3 |
4 | .. list-table::
5 | :header-rows: 1
6 |
7 | * - Identifier
8 | - Alternative Architecture Names
9 | - Endianness
10 | - Architecture Type
11 | * - ``amd64``
12 | - x86-64, x86_64, x64, AMD64, Intel 64
13 | - :term:`Little-Endian`
14 | - :term:`CISC`
15 | * - ``i386`` [1]_
16 | - Intel x86, 80x86
17 | - :term:`Little-Endian`
18 | - :term:`CISC`
19 | * - ``arm64``
20 | - ARM64, ARMv8, AArch64
21 | - :term:`Little-Endian`
22 | - :term:`RISC`
23 | * - ``armhf``
24 | - ARM32, ARMv7, AArch32, ARM Hard Float
25 | - :term:`Little-Endian`
26 | - :term:`RISC`
27 | * - ``ppc64el``
28 | - PowerPC64 Little-Endian
29 | - :term:`Little-Endian`
30 | - :term:`RISC`
31 | * - ``powerpc``
32 | - PowerPC (32-bit)
33 | - :term:`Big-Endian`
34 | - :term:`RISC`
35 | * - ``s390x``
36 | - IBM System z, S/390, S390X
37 | - :term:`Big-Endian`
38 | - :term:`CISC`
39 | * - ``riscv64``
40 | - RISC-V (64-bit)
41 | - :term:`Little-Endian`
42 | - :term:`RISC`
43 |
44 | .. [1] ``i386`` is a partial-port of Ubuntu, which is supported as a multi-arch
45 | supplementary architecture. There is no kernel, no installers, and no
46 | bootloaders for ``i386``, therefore it cannot be booted as a pure ``i386``
47 | installation. You have to crossbuild ``i386`` or build in a ``i386`` chroot
48 | on a ``amd64`` host.
49 |
50 | Other architectures
51 | -------------------
52 |
53 | :term:`Ubuntu` doesn't currently support any other :term:`architectures `.
54 | This doesn't mean that Ubuntu won't run on other architectures -- in fact it is
55 | entirely possible for it to install without a problem, because Ubuntu
56 | is based on the :term:`Debian` distribution, which has support for eight
57 | additional architectures (see `Debian Supported Architectures `_).
58 |
59 | However, if you run into problems, the Ubuntu community may not be able to help you.
60 |
61 | Resources
62 | ---------
63 |
64 | - `Ubuntu Wiki -- Supported Architectures `_
65 | - `Ubuntu Wiki -- i386 `_
66 | - `Statement on 32-bit i386 packages for Ubuntu 19.10 and 20.04 LTS `_
67 | - `Ubuntu Wiki -- S390X `_
68 | - `Ubuntu Downloads `_
69 | - `Endianness `_
--------------------------------------------------------------------------------
/docs/explanation/sponsorship.rst:
--------------------------------------------------------------------------------
1 | .. _sponsorship:
2 |
3 | Sponsorship
4 | ===========
5 |
6 | Sponsorship is a process that allows developers without upload rights to submit their patches or new packages for review. If approved, an authorised developer will upload the changes on their behalf.
7 |
8 | When can you request sponsorship?
9 | ---------------------------------
10 |
11 | Since upload rights are carefully managed to ensure system stability and security, new contributors don't have them. So if you don't have upload rights, you can request sponsorship in the following situations:
12 |
13 | - Making changes to existing packages or incremental updates.
14 | - Submitting security updates or bug fixes.
15 | - Introducing new packages to Ubuntu.
16 |
17 | Requesting sponsorship
18 | ----------------------
19 |
20 | To request sponsorship, follow these steps:
21 |
22 | 1. `File an Ubuntu bug in Launchpad `_ or follow up on an existing one.
23 | #. Add the necessary files, such as patches or ``.diff.gz`` files, according to the package's requirements. If the change is a patch, follow the patch tagging guidelines. For security updates, follow the security update packaging guidelines described in `Packaging `_.
24 | #. Link your changes to the bug. See `Seeking Sponsorship `_.
25 | #. Subscribe ``ubuntu-sponsors`` or ``ubuntu-security-sponsors`` to the bug.
26 |
27 | Sponsoring a patch
28 | ------------------
29 |
30 | Members of the :term:`Ubuntu Sponsors` and :term:`Ubuntu Security Sponsors` teams have the right to sponsor patches or new packages. If you are interested in sponsoring, you can apply to join these teams.
31 |
32 | Responding to feedback from sponsors
33 | ------------------------------------
34 |
35 | If a sponsor reviews your changes and requests further modifications, make the modifications to the branch you were working on, then commit them by running:
36 |
37 | .. code-block:: none
38 |
39 | $ bzr commit
40 |
41 | Now, push your modifications to :term:`Launchpad`. Since ``bzr`` remembers the previous push location, you can run:
42 |
43 | .. code-block:: none
44 |
45 | $ bzr push
46 |
47 | After pushing your modifications, reply to the sponsor's request explaining the modifications you made and request a re-review. You can also respond directly on the merge proposal page in Launchpad.
48 |
49 | Resources
50 | ---------
51 |
52 | - `Sponsorship Process `_
53 | - `Seeking Sponsorship `_
54 | - `Update Preparation `_
55 | - `Seeking Review and Sponsorship `_
56 |
--------------------------------------------------------------------------------
/docs/how-to/extract-packages.rst:
--------------------------------------------------------------------------------
1 | Extract packages
2 | ================
3 |
4 | This article demonstrates how to extract the contents of Debian packages.
5 |
6 | See also the article :doc:`/explanation/package-model` for a deeper
7 | understanding of package formats.
8 |
9 | .. _ExtractSourcePackage:
10 |
11 | Extract a source package
12 | ------------------------
13 |
14 | This section demonstrates how to extract the content of a source package.
15 |
16 | .. note::
17 |
18 | A source package archive has the file extension `.dsc`.
19 | See also the manual page :manpage:`dsc(5)` for further information.
20 |
21 | .. important::
22 |
23 | Make sure that you have the `dpkg-dev` package installed.
24 | To install it, run the following commands in a terminal:
25 |
26 | .. code-block:: none
27 |
28 | sudo apt update && sudo apt install dpkg-dev
29 |
30 | Run the following command in a terminal:
31 |
32 | .. code-block:: none
33 |
34 | dpkg-source --extract SOURCE-PACKAGE.dsc [OUTPUT-DIRECTORY]
35 |
36 | ``SOURCE-PACKAGE.dsc``
37 | The path to the source package control file.
38 |
39 | ``OUTPUT-DIRECTORY`` (optional)
40 | The path to the directory where to extract the content of the source
41 | package to. This directory **must not** exist. If no output directory is
42 | specified, the content is extracted into a directory named
43 | ``NAME-VERSION`` (where ``NAME`` is the name of the source package and
44 | ``VERSION`` its version) under the current working directory.
45 |
46 | See the manual page :manpage:`dpkg-source(1)` for further information.
47 |
48 | .. _ExtractBinaryPackage:
49 |
50 | Extract a binary package
51 | ------------------------
52 |
53 | This section demonstrates how to extract the content a binary package.
54 |
55 | .. note::
56 |
57 | A binary package archive has the file extension `.deb`.
58 | See also the manual page :manpage:`deb(5)` for further information.
59 |
60 | Run the following command in a terminal:
61 |
62 | .. code-block:: none
63 |
64 | dpkg-deb --extract BINARY-PACKAGE.deb OUTPUT-DIRECTORY
65 |
66 | ``BINARY-PACKAGE.deb``
67 | The path to the binary package control file.
68 |
69 | ``OUTPUT-DIRECTORY``
70 | The path to the directory where to extract the content of the binary
71 | package to. In comparison to :ref:`ExtractSourcePackage`, this directory
72 | can already exist and even contain files.
73 |
74 | See the manual page :manpage:`dpkg-deb(1)` for further information.
75 |
76 | .. tip::
77 |
78 | Using ``--vextract`` instead of ``--extract`` also outputs a list of
79 | the extracted files to :term:`standard output `.
80 |
81 | To just list the files that the package contains, use the ``--contents`` option:
82 |
83 | .. code-block:: none
84 |
85 | dpkg-deb --contents BINARY-PACKAGE.deb
86 |
87 | .. tip::
88 |
89 | You can also replace ``dpkg-deb`` with ``dpkg`` for the examples
90 | demonstrated here. ``dpkg`` forwards the options to ``dpkg-deb``.
91 | See the manual page :manpage:`dpkg(1)` for further information.
92 |
--------------------------------------------------------------------------------
/snap/snapcraft.yaml:
--------------------------------------------------------------------------------
1 | name: ubuntu-packaging-guide
2 | title: Ubuntu Packaging Guide
3 | base: core22
4 | summary: A web-based guide/reference about Ubuntu development and deb packaging.
5 | description: |
6 | This snap provides an HTTP file server that hosts the Ubuntu Packaging Guide locally on your machine. This allows you to access the guide even when you are offline or have a poor internet connection.
7 |
8 | The web server listens by default on the address `http://localhost:9000`
9 |
10 | To launch a browser with the listening address, run the command:
11 | `ubuntu-packaging-guide browse`
12 |
13 | To change the listening address, use the commands:
14 | `snap set ubuntu-packaging-guide http.port=VALUE`
15 | `snap set ubuntu-packaging-guide http.address=VALUE`
16 |
17 | To stop/restart/start the web server, use the commands:
18 | `snap stop ubuntu-packaging-guide.deamon`
19 | `snap restart ubuntu-packaging-guide.deamon`
20 | `snap start ubuntu-packaging-guide.deamon`
21 |
22 | See more details by running the command:
23 | `ubuntu-packaging-guide --help`
24 | icon: snap/local/ubuntu-logo.png
25 | license: CC-BY-3.0
26 | source-code: https://github.com/canonical/ubuntu-packaging-guide
27 | issues: https://github.com/canonical/ubuntu-packaging-guide/issues
28 | website: https://packaging.ubuntu.com/
29 | adopt-info: metadata
30 |
31 | grade: devel
32 | confinement: strict
33 | architectures:
34 | - build-on: [amd64]
35 | build-for: [amd64]
36 | - build-on: [amd64]
37 | build-for: [arm64]
38 |
39 | parts:
40 | metadata:
41 | source: .
42 | plugin: nil
43 | build-packages:
44 | - python3
45 | override-build: |
46 | git rev-parse HEAD > COMMIT-HASH
47 | python3 snap/local/eng/print-version.py > VERSION
48 | craftctl set version="$(cat VERSION)+git.$(git rev-parse --short HEAD)"
49 | mv COMMIT-HASH "$SNAPCRAFT_PART_INSTALL"
50 | mv VERSION "$SNAPCRAFT_PART_INSTALL"
51 | craftctl default
52 | organize:
53 | COMMIT-HASH: usr/share/ubuntu-packaging-guide/meta/COMMIT-HASH
54 | VERSION: usr/share/ubuntu-packaging-guide/meta/VERSION
55 | html-pages:
56 | source: ./docs
57 | plugin: nil
58 | build-packages:
59 | - python3
60 | - python3-pip
61 | override-build: |
62 | python3 build_requirements.py
63 | pip3 install -r .sphinx/requirements.txt
64 | sphinx-build -b dirhtml . "$SNAPCRAFT_PART_INSTALL/dist" -c . -d .sphinx/.doctrees
65 | craftctl default
66 | organize:
67 | dist: usr/share/ubuntu-packaging-guide/www
68 | file-server:
69 | source: snap/local/src
70 | plugin: dump
71 | organize:
72 | cli.py: usr/bin/cli
73 | deamon.py: usr/bin/deamon
74 | common.py: usr/lib/ubuntu-packaging-guide/common.py
75 | stage-packages:
76 | - python3
77 | override-stage: |
78 | craftctl default
79 | chmod 555 usr/bin/cli usr/bin/deamon
80 |
81 | apps:
82 | ubuntu-packaging-guide:
83 | command: usr/bin/cli
84 | environment:
85 | PYTHONPATH: $SNAP/usr/lib/ubuntu-packaging-guide
86 | plugs:
87 | - desktop
88 | deamon:
89 | command: usr/bin/deamon
90 | daemon: simple
91 | environment:
92 | PYTHONPATH: $SNAP/usr/lib/ubuntu-packaging-guide
93 | plugs:
94 | - network
95 | - network-bind
96 |
--------------------------------------------------------------------------------
/docs/explanation/patches.rst:
--------------------------------------------------------------------------------
1 | Patches
2 | =======
3 |
4 | Patches record modifications to :term:`source code`. Patches can come in many
5 | forms, including but not limited to:
6 |
7 | - :term:`Upstream` features or bug-fixes not present in the current release.
8 | - :term:`Ubuntu` specific changes, such as custom defaults and theming.
9 | - :term:`CVE` fixes and other security-related updates.
10 |
11 | All changes to a :term:`source package` in the ``3.0 (quilt)`` format (see
12 | :ref:`explanation `) to the source files
13 | (all files inside the :term:`orig tarball` / outside the ``debian/``
14 | directory) must be applied in the form of a patch.
15 |
16 | Changes to a source package in the ``3.0 (native)`` format (see
17 | :ref:`explanation `) get applied directly
18 | and will not be further discussed in this article.
19 |
20 | It is important to treat patches with care, and ensure the format and headers
21 | follow best practices. This makes it easier to maintain a package long-term.
22 | In Ubuntu, we try to follow the :term:`DEP 3` specification, which details a
23 | standard format for patch headers.
24 |
25 | The source package stores the patches in the :file:`debian/patches/` directory.
26 | These patches get applied from top to bottom in the order they are listed in
27 | :file:`debian/patches/series`, excluding empty lines and lines starting with ``#``.
28 |
29 | Sending patches upstream
30 | ------------------------
31 |
32 | Changes to the upstream source code which are not Ubuntu specific should be sent
33 | to the upstream authors in whatever form they prefer. This allows the upstream
34 | authors to include the patch in the upstream version of the package.
35 |
36 | When you should (not) rewrite a patch header to follow DEP 3
37 | ------------------------------------------------------------
38 |
39 | You **should** rewrite a patch header to follow DEP 3 if:
40 |
41 | * You are introducing a new patch altogether.
42 | * You are making substantive modifications to an existing patch.
43 | * More information is known about the patch, and a DEP 3 header would contain
44 | updated information.
45 |
46 | You **should not** rewrite a patch header to follow DEP 3 if:
47 |
48 | * You are preparing a non-:term:`micro-release exception SRU `
49 | and changing the patch header is not directly related to the bug being fixed.
50 | * You intend on keeping only the modifications to the header as part of the
51 | :term:`Ubuntu delta` without making substantive changes to the diff contents,
52 | and have no plans to forward it to :term:`Debian`.
53 | * The team claiming responsibility for this package in Ubuntu explicitly
54 | disagrees with the usage of DEP 3 headers. (This should be brought up on the
55 | ubuntu-devel mailing list.)
56 |
57 | Resources
58 | ---------
59 |
60 | - :doc:`Patch management with quilt (how-to) `
61 | - :doc:`DEP 3 -- Patch file headers (reference) `
62 | - `Debian Policy Section 4.3. -- Changes to the upstream sources `_
63 | - `Debian Policy Section 4.13. -- Embedded code copies `_
64 | - `Debian Policy Section 4.17. -- Vendor-specific patch series `_
65 | - `Debian Policy Appendix 7. -- Diversions - overriding a package's version of a file (from old Packaging Manual) `_
66 |
--------------------------------------------------------------------------------
/docs/404.svg:
--------------------------------------------------------------------------------
1 |
2 |
3 |
14 |
--------------------------------------------------------------------------------
/docs/conf.py:
--------------------------------------------------------------------------------
1 | import sys
2 |
3 | sys.path.append('./')
4 | from custom_conf import *
5 |
6 | # Configuration file for the Sphinx documentation builder.
7 | # You should not do any modifications to this file. Put your custom
8 | # configuration into the custom_conf.py file.
9 | # If you need to change this file, contribute the changes upstream.
10 | #
11 | # For the full list of built-in configuration values, see the documentation:
12 | # https://www.sphinx-doc.org/en/master/usage/configuration.html
13 |
14 | ############################################################
15 | ### Extensions
16 | ############################################################
17 |
18 | extensions = [
19 | 'sphinx_design',
20 | 'sphinx_copybutton',
21 | 'sphinxcontrib.jquery',
22 | ]
23 |
24 | extensions.extend(custom_extensions)
25 |
26 | ### Configuration for extensions
27 |
28 | # Used for related links
29 | if not 'discourse_prefix' in html_context and 'discourse' in html_context:
30 | html_context['discourse_prefix'] = html_context['discourse'] + '/t/'
31 |
32 | # Default image for OGP (to prevent font errors, see
33 | # https://github.com/canonical/sphinx-docs-starter-pack/pull/54 )
34 | if not 'ogp_image' in locals():
35 | ogp_image = 'https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg'
36 |
37 | ############################################################
38 | ### General configuration
39 | ############################################################
40 |
41 | exclude_patterns = [
42 | '_build',
43 | 'Thumbs.db',
44 | '.DS_Store',
45 | '.sphinx',
46 | ]
47 | exclude_patterns.extend(custom_excludes)
48 |
49 | rst_epilog = '''
50 | .. include:: /reuse/links.txt
51 | '''
52 | if 'custom_rst_epilog' in locals():
53 | rst_epilog = custom_rst_epilog
54 |
55 | source_suffix = {
56 | '.rst': 'restructuredtext',
57 | '.md': 'markdown',
58 | }
59 |
60 | if not 'conf_py_path' in html_context and 'github_folder' in html_context:
61 | html_context['conf_py_path'] = html_context['github_folder']
62 |
63 | # For ignoring specific links
64 | linkcheck_anchors_ignore_for_url = [
65 | r'https://github\.com/.*'
66 | ]
67 | linkcheck_anchors_ignore_for_url.extend(custom_linkcheck_anchors_ignore_for_url)
68 |
69 | # Tags cannot be added directly in custom_conf.py, so add them here
70 | for tag in custom_tags:
71 | tags.add(tag)
72 |
73 | ############################################################
74 | ### Styling
75 | ############################################################
76 |
77 | # Find the current builder
78 | builder = 'dirhtml'
79 | if '-b' in sys.argv:
80 | builder = sys.argv[sys.argv.index('-b')+1]
81 |
82 | # Setting templates_path for epub makes the build fail
83 | if builder == 'dirhtml' or builder == 'html':
84 | templates_path = ['.sphinx/_templates']
85 |
86 | # Theme configuration
87 | html_theme = 'furo'
88 | html_last_updated_fmt = ''
89 | html_permalinks_icon = '¶'
90 |
91 | if html_title == '':
92 | html_theme_options = {
93 | 'sidebar_hide_name': True
94 | }
95 |
96 | ############################################################
97 | ### Additional files
98 | ############################################################
99 |
100 | html_static_path = ['.sphinx/_static']
101 |
102 | html_css_files = [
103 | 'custom.css',
104 | 'header.css',
105 | 'github_issue_links.css',
106 | 'furo_colors.css'
107 | ]
108 | html_css_files.extend(custom_html_css_files)
109 |
110 | html_js_files = ['header-nav.js']
111 | if 'github_issues' in html_context and html_context['github_issues'] and not disable_feedback_button:
112 | html_js_files.append('github_issue_links.js')
113 | html_js_files.extend(custom_html_js_files)
114 |
--------------------------------------------------------------------------------
/docs/explanation/main-inclusion-review.rst:
--------------------------------------------------------------------------------
1 | Main Inclusion Review (MIR)
2 | ===========================
3 |
4 | .. important::
5 |
6 | Do not confuse the abbreviation :term:`MIR` with the `display server `_ Mir.
7 |
8 | :term:`Packages ` in :term:`Main` and :term:`Restricted` are officially
9 | maintained, supported and recommended by the :term:`Ubuntu` project.
10 | :term:`Canonical's ` support services applies to these packages,
11 | which include security updates and certain :term:`SLA` guarantees when bugs are reported
12 | and technical support is requested.
13 |
14 | Therefore, special consideration is necessary before adding new packages
15 | to Main or Restricted. The Ubuntu :term:`MIR Team` reviews packages for promotion:
16 |
17 | - from :term:`Universe` to :term:`Main`, or
18 | - from :term:`Multiverse` to :term:`Restricted`.
19 |
20 | This review process is called **Main Inclusion Review (MIR)**.
21 |
22 | Submit a package for Main Inclusion Review
23 | ------------------------------------------
24 |
25 | The `Main Inclusion Review documentation `_
26 | by the MIR team provides instructions on how to apply for
27 | :term:`Main Inclusion Review` for a package. The documentation even contains
28 | details of how the application gets reviewed by the MIR team.
29 |
30 | .. note::
31 |
32 | The guidelines and review process is constantly evolving. Therefore you
33 | should re-read the MIR documentation even if you have submitted a package
34 | for Main Inclusion Review in the past.
35 |
36 | The MIR documentation is also a living document. External contributions,
37 | suggestions, discussions or questions about the process are always welcome.
38 |
39 | MIR team weekly meeting
40 | -----------------------
41 |
42 | The MIR team holds weekly meetings every Tuesday at 16:30 CET on the
43 | :term:`IRC` server ``irc.libera.chat`` in the ``#ubuntu-meeting`` channel.
44 | You can follow these `instructions `_ on
45 | how to connect to ``irc.libera.chat``.
46 |
47 | The purpose of the meeting is:
48 |
49 | - to distribute the workload fairly between the members of the MIR team
50 | - to provide a timely response to reporters of MIR applications
51 | - detection and discussion of any current or complex cases
52 |
53 | You should attend these meetings if you submit an MIR request until it is approved or rejected.
54 |
55 | Usually, the amount of MIR requests increases during the six-month development
56 | period of a new Ubuntu release. Especially right before the various feature freezes
57 | (see :doc:`/explanation/development-process`), Ubuntu developers submit MIR requests
58 | they have been working on before they have to submit an exception request. As a result,
59 | the meetings tend to be quieter, and response times to MIR requests are, on average,
60 | faster after the release of a new Ubuntu version.
61 |
62 | Resources
63 | ---------
64 |
65 | - `Main Inclusion Review documentation `_ by the MIR team
66 | - `MIR process overview `_
67 | - `MIR application template `_
68 | - `Helper tools `_
69 | - `Bug lists `_
70 | - `Pull requests `_
71 | - `Issues `_
72 | - MIR team on :term:`Launchpad`: |MainInclusionReviewTeamLaunchpadGroup|_
73 |
74 | .. _MainInclusionReviewDocumentation: https://github.com/canonical/ubuntu-mir
75 | .. _MainInclusionReviewTeamLaunchpadGroup: https://launchpad.net/~ubuntu-mir
76 | .. |MainInclusionReviewTeamLaunchpadGroup| replace:: ``~ubuntu-mir``
77 |
--------------------------------------------------------------------------------
/docs/explanation/debian-merges-and-syncs.rst:
--------------------------------------------------------------------------------
1 | Importing changes from Debian (merges & syncs)
2 | ==============================================
3 |
4 | This article explains how and why changes from :term:`Debian` are imported
5 | into Ubuntu.
6 |
7 | How does Ubuntu import changes from Debian?
8 | -------------------------------------------
9 |
10 | Because Ubuntu is derived from Debian and uses the same package management
11 | system (:term:`APT`), most changes made to Debian can also be applied to
12 | Ubuntu.
13 |
14 | **Syncs** and **merges** are the two processes through which Ubuntu developers
15 | integrate updates and improvements from Debian into the
16 | :doc:`/explanation/archive`.
17 |
18 | Sync
19 | ~~~~
20 |
21 | Beginning with the archive opening for a new Ubuntu release until the
22 | :ref:`DebianImportFreeze`, new :term:`packages ` and packages with
23 | higher version identifiers than the corresponding Ubuntu packages are
24 | automatically copied from Debian unstable (also known as :term:`Code name`
25 | "Sid") into the Ubuntu package archive if the corresponding Ubuntu packages
26 | do not carry :term:`Ubuntu Delta`. This process is called "synchronisation with
27 | Debian", or "sync" for short.
28 |
29 | On request (via a :term:`Launchpad` bug-ticket),
30 | :term:`Archive Admins ` can sync a package from Debian even if
31 | the Ubuntu package carries Ubuntu Delta. In this case, the Ubuntu Delta will
32 | be dropped. A good example is when Ubuntu-specific changes have been merged
33 | into the Debian package or :term:`Upstream` project and are no longer needed.
34 |
35 | .. note::
36 | The :ref:`FeatureFreeze` is often scheduled for the same day as the
37 | :ref:`DebianImportFreeze`.
38 |
39 | After the Debian Import Freeze and before the :ref:`FinalRelease`, you
40 | must also request the respective freeze exception.
41 |
42 | After the Final Release, you must follow the
43 | :ref:`StableReleaseUpdates_Summary` process. For additional details
44 | about the freezes, see the :doc:`/explanation/development-process` article.
45 |
46 | Merges
47 | ~~~~~~
48 |
49 | When importing a newer Debian package into Ubuntu, a merge must be performed
50 | if the corresponding Ubuntu package carries Ubuntu Delta that needs to be
51 | partially or fully applied to the Debian package.
52 |
53 | The Ubuntu Merge-o-Matic (MoM) automatically performs merges and publishes the
54 | reports on `this page `_. See the lists of
55 | outstanding merges for:
56 |
57 | * `main `_
58 | * `universe `_
59 | * `restricted `_
60 | * `multiverse `_
61 |
62 | To complete a merge, interaction and supervision by Ubuntu maintainers are
63 | required. See the :doc:`tutorial ` and
64 | :doc:`how-to ` for details on performing a merge.
65 |
66 | See the section :ref:`ArchiveComponents` in the article that explains the
67 | Ubuntu package archive for an explanation of ``main``, ``universe``,
68 | ``restricted`` and ``multiverse``.
69 |
70 | Why does Ubuntu import changes from Debian?
71 | -------------------------------------------
72 |
73 | Ubuntu incorporates changes from Debian through merging and syncing to
74 | leverage the extensive work and improvements made by the Debian community.
75 | Debian provides a stable foundation and a vast repository of packages.
76 | By integrating changes from Debian, Ubuntu can focus on refining the
77 | :term:`user experience`. At the same time, the consistency between Ubuntu and
78 | Debian allows for sharing resources (e.g., testing and bug fixing) and
79 | contributing back to the open-source ecosystem, ultimately benefiting both
80 | :term:`distributions ` and their users.
81 |
--------------------------------------------------------------------------------
/docs/contribute.rst:
--------------------------------------------------------------------------------
1 | Contribute to the Ubuntu Packaging Guide
2 | ****************************************
3 |
4 | The `Ubuntu Packaging Guide `_ is an open source project that warmly welcomes
5 | community contributions and suggestions.
6 |
7 | This document describes how to contribute changes to the Ubuntu Packaging
8 | Guide. If you don't already have a GitHub account, you can
9 | `sign up on their website `_.
10 |
11 | How to contribute
12 | =================
13 |
14 | I want to raise an issue
15 | ------------------------
16 |
17 | We use GitHub issues to track things that need to be fixed. If you find a
18 | problem and want to report it to us, you can click on the "Give feedback"
19 | button at the top of any page in the Guide, and it will open an issue for you.
20 |
21 | Alternatively, you can
22 | `open an issue directly `_
23 | and describe the problem you're having, or the suggestion you want to add.
24 |
25 | I have a question about packaging
26 | ---------------------------------
27 |
28 | If you're stuck and have a question, you can use our GitHub discussion board to
29 | `ask, or start a discussion `_.
30 |
31 | Note that we may not be able to respond immediately, so please be patient!
32 |
33 | I want to submit a fix
34 | ----------------------
35 |
36 | If you found an issue and want to submit a fix for it, or have written a guide
37 | you would like to add to the documentation, feel free to
38 | `open a pull request to submit your fix `_
39 | against our ``2.0-preview`` branch. If you need help, please use the discussion board
40 | or contact one of the repository administrators.
41 |
42 | Contribution format for the project
43 | ===================================
44 |
45 | Sphinx & reStructuredText
46 | -------------------------
47 |
48 | The Guide is built using `Sphinx `_. Articles should
49 | be written in reStructuredText. The following links might be helpful:
50 |
51 | * `A ReStructuredText Primer `_
52 | * `Quick reStructuredText `_
53 |
54 | How to add a new Sphinx extension
55 | ---------------------------------
56 |
57 | In general, there are two places you will need to update to add new extensions.
58 |
59 | * ``docs/conf.py`` - add the name of the extension to the extensions configuration
60 | parameter
61 | * ``docs/.sphinx/requirements.txt`` - add the name of the extension to the
62 | bottom of the list
63 |
64 | The documentation for most Sphinx extensions will tell you what text to add
65 | to the ``conf.py`` file, as in this example: ::
66 |
67 | extensions = [
68 | 'sphinx_copybutton',
69 | 'sphinx_design',
70 | ]
71 |
72 | Translations
73 | ------------
74 |
75 | We use the localisation (l10n) module for Sphinx and gettext for translating
76 | the Ubuntu Packaging Guide.
77 |
78 | Some notes about translating the guide:
79 |
80 | - Some formatting is part of reStructuredText and should not be changed,
81 | including emphasis (which uses asterisks or underscores), paragraph ending
82 | before a code block (``::``) and double backtick quotes (``````).
83 |
84 | - The Guide uses email-style reStructuredText links. If you see a link in
85 | the text like::
86 |
87 | `Translatable link text `_
88 |
89 | Then replace the "Translatable link text" with your translations, but keep
90 | the ``Link_Reference`` unchanged (even if it is in English). The same applies
91 | if a URL is used instead of ``Link_Reference``.
92 |
93 | To test your translation, use ``make BUILDER-LANGUAGE`` command (for example,
94 | ``make html-it`` will build HTML docs in Italian language).
95 |
--------------------------------------------------------------------------------
/docs/.sphinx/_templates/footer.html:
--------------------------------------------------------------------------------
1 | {# ru-fu: copied from Furo, with modifications as stated below. Modifications are marked 'mod:'. #}
2 |
3 |
4 | {# mod: Per-page navigation #}
5 | {% if meta %}
6 | {% if 'sequential_nav' in meta %}
7 | {% set sequential_nav = meta.sequential_nav %}
8 | {% endif %}
9 | {% endif %}
10 | {# mod: Conditional wrappers to control page navigation buttons #}
11 | {% if sequential_nav != "none" -%}
12 | {% if next and (sequential_nav == "next" or sequential_nav == "both") -%}
13 |
14 |
105 |
106 |
--------------------------------------------------------------------------------
/docs/.sphinx/_static/header.css:
--------------------------------------------------------------------------------
1 | .p-navigation {
2 | border-bottom: 1px solid var(--color-sidebar-background-border);
3 | }
4 |
5 | .p-navigation__nav {
6 | background: #333333;
7 | display: flex;
8 | }
9 |
10 | .p-logo {
11 | display: flex !important;
12 | padding-top: 0 !important;
13 | text-decoration: none;
14 | }
15 |
16 | .p-logo-image {
17 | height: 44px;
18 | padding-right: 10px;
19 | }
20 |
21 | .p-logo-text {
22 | margin-top: 18px;
23 | color: white;
24 | text-decoration: none;
25 | }
26 |
27 | ul.p-navigation__links {
28 | display: flex;
29 | list-style: none;
30 | margin-left: 0;
31 | margin-top: auto;
32 | margin-bottom: auto;
33 | max-width: 800px;
34 | width: 100%;
35 | }
36 |
37 | ul.p-navigation__links li {
38 | margin: 0 auto;
39 | text-align: center;
40 | width: 100%;
41 | }
42 |
43 | ul.p-navigation__links li a {
44 | background-color: rgba(0, 0, 0, 0);
45 | border: none;
46 | border-radius: 0;
47 | color: var(--color-sidebar-link-text);
48 | display: block;
49 | font-weight: 400;
50 | line-height: 1.5rem;
51 | margin: 0;
52 | overflow: hidden;
53 | padding: 1rem 0;
54 | position: relative;
55 | text-align: left;
56 | text-overflow: ellipsis;
57 | transition-duration: .1s;
58 | transition-property: background-color, color, opacity;
59 | transition-timing-function: cubic-bezier(0.215, 0.61, 0.355, 1);
60 | white-space: nowrap;
61 | width: 100%;
62 | }
63 |
64 | ul.p-navigation__links .p-navigation__link {
65 | color: #ffffff;
66 | font-weight: 300;
67 | text-align: center;
68 | text-decoration: none;
69 | }
70 |
71 | ul.p-navigation__links .p-navigation__link:hover {
72 | background-color: #2b2b2b;
73 | }
74 |
75 | ul.p-navigation__links .p-dropdown__link:hover {
76 | background-color: var(--color-sidebar-item-background--hover);
77 | }
78 |
79 | ul.p-navigation__links .p-navigation__sub-link {
80 | background: var(--color-background-primary);
81 | padding: .5rem 0 .5rem .5rem;
82 | font-weight: 300;
83 | }
84 |
85 | ul.p-navigation__links .more-links-dropdown li a {
86 | border-left: 1px solid var(--color-sidebar-background-border);
87 | border-right: 1px solid var(--color-sidebar-background-border);
88 | }
89 |
90 | ul.p-navigation__links .more-links-dropdown li:first-child a {
91 | border-top: 1px solid var(--color-sidebar-background-border);
92 | }
93 |
94 | ul.p-navigation__links .more-links-dropdown li:last-child a {
95 | border-bottom: 1px solid var(--color-sidebar-background-border);
96 | }
97 |
98 | ul.p-navigation__links .p-navigation__logo {
99 | padding: 0.5rem;
100 | }
101 |
102 | ul.p-navigation__links .p-navigation__logo img {
103 | width: 40px;
104 | }
105 |
106 | ul.more-links-dropdown {
107 | display: none;
108 | overflow-x: visible;
109 | height: 0;
110 | z-index: 55;
111 | padding: 0;
112 | position: relative;
113 | list-style: none;
114 | margin-bottom: 0;
115 | margin-top: 0;
116 | }
117 |
118 | .nav-more-links::after {
119 | background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16'%3E%3Cpath fill='%23111' d='M8.187 11.748l6.187-6.187-1.06-1.061-5.127 5.127L3.061 4.5 2 5.561z'/%3E%3C/svg%3E");
120 | background-position: center;
121 | background-repeat: no-repeat;
122 | background-size: contain;
123 | content: "";
124 | display: block;
125 | filter: invert(100%);
126 | height: 1rem;
127 | pointer-events: none;
128 | position: absolute;
129 | right: 1rem;
130 | text-indent: calc(100% + 10rem);
131 | top: calc(1rem + 0.25rem);
132 | width: 1rem;
133 | }
134 |
135 | .nav-ubuntu-com {
136 | display: none;
137 | }
138 |
139 | @media only screen and (min-width: 480px) {
140 | ul.p-navigation__links li {
141 | width: 100%;
142 | }
143 |
144 | .nav-ubuntu-com {
145 | display: inherit;
146 | }
147 | }
148 |
149 | @media only screen and (max-width: 800px) {
150 | .nav-more-links {
151 | margin-left: auto !important;
152 | padding-right: 2rem !important;
153 | width: 8rem !important;
154 | }
155 | }
156 |
157 | @media only screen and (min-width: 800px) {
158 | ul.p-navigation__links li {
159 | width: 100% !important;
160 | }
161 | }
162 |
163 | @media only screen and (min-width: 1310px) {
164 | ul.p-navigation__links {
165 | margin-left: calc(50% - 41em);
166 | }
167 | }
168 |
--------------------------------------------------------------------------------
/snap/local/src/cli.py:
--------------------------------------------------------------------------------
1 | #!/usr/bin/python3
2 |
3 | import argparse
4 | import subprocess
5 |
6 | from common import *
7 |
8 | ___DESCRIPTION___ = ("This is a convenience tool to disply information of the "
9 | "local version of the Ubuntu Packaging Guide and launch "
10 | "a browser to the location of the HTTP file server.")
11 |
12 | ___EPILOG___ = ("Read more about this project:\n"
13 | "https://github.com/canonical/ubuntu-packaging-guide\n"
14 | "\n"
15 | "Set the HTTP port with:\n"
16 | " $ snap set ubuntu-packaging-guide http.port=VALUE\n"
17 | "\n"
18 | "Set the HTTP address with:\n"
19 | " $ snap set ubuntu-packaging-guide http.address=VALUE\n"
20 | "\n"
21 | "Stop the HTTP file server deamon:\n"
22 | " $ snap stop ubuntu-packaging-guide.deamon\n"
23 | "\n"
24 | "Start the HTTP file server deamon:\n"
25 | " $ snap start ubuntu-packaging-guide.deamon\n"
26 | "\n"
27 | "Restart the HTTP file server deamon:\n"
28 | " $ snap restart ubuntu-packaging-guide.deamon\n")
29 |
30 |
31 | def ParseArguments():
32 | parser = argparse.ArgumentParser(prog="ubuntu-packaging-guide",
33 | description=___DESCRIPTION___,
34 | epilog=___EPILOG___,
35 | formatter_class=argparse.RawTextHelpFormatter, # noqa: E501
36 | add_help=False)
37 |
38 | parser.add_argument("-h", "--help",
39 | action="help",
40 | help="Display help, how to use this command.")
41 |
42 | parser.add_argument("-v", "--version",
43 | action="version",
44 | version="%(prog)s 2.0",
45 | help="Display the local version of the "
46 | "Ubuntu Packaging Guide.")
47 |
48 | commands = parser.add_subparsers(title="commands",
49 | dest="command",
50 | help="default: browse "
51 | "(if no command is specified)",
52 | required=False)
53 | commands.add_parser("info",
54 | help="Display information about the local version of "
55 | "the Ubuntu Packaging Guide and the HTTP file "
56 | "server deamon.")
57 | commands.add_parser("browse",
58 | help="Opens the Ubuntu Packaging Guide in a browser "
59 | "(the HTTP file server deamon needs to be "
60 | "running)")
61 |
62 | return parser.parse_args()
63 |
64 |
65 | def LaunchBrowser(address):
66 | subprocess.check_call(["xdg-open", address])
67 |
68 |
69 | def main():
70 | arguments = ParseArguments()
71 |
72 | match arguments.command:
73 | case "info":
74 | print("Ubuntu Packaging Guide\n"
75 | f" Version: {GetVersion()}\n"
76 | f" Commit: {GetCommitHash()}\n"
77 | "\n"
78 | "File Server:\n"
79 | f" HTTP Address: {GetHttpAddress()}\n"
80 | f" HTTP Port: {GetHttpPort()}\n"
81 | f" Root Path: {GetBasePath()}\n"
82 | f" Status: {GetDeamonStatus()}")
83 |
84 | # case "browse":
85 | case _:
86 | match GetDeamonStatus():
87 | case "active":
88 | print("Lauching browser...")
89 |
90 | address = f"http://{GetHttpAddress()}:{GetHttpPort()}"
91 | LaunchBrowser(address)
92 | case _:
93 | print("The HTTP file server deamon is not active. "
94 | "To fix this:\n"
95 | "\n"
96 | " 1. Start the deamon:\n"
97 | " $ snap start ubuntu-packaging-guide.deamon\n"
98 | " 2. Run this command again:\n"
99 | " $ ubuntu-packaging-guide browse\n")
100 |
101 |
102 | if __name__ == '__main__':
103 | main()
104 |
--------------------------------------------------------------------------------
/docs/reference/debian-policy.rst:
--------------------------------------------------------------------------------
1 | Debian policy
2 | =============
3 |
4 | The Debian policy defines the requirements and guidelines for packages in the Debian distribution. It governs how packages should behave, how they interact with each other, and how they fit into the system as a whole.
5 |
6 | The policy specifies:
7 |
8 | - the structure and contents of the Debian archive
9 | - mandatory technical requirements for inclusion in the distribution
10 | - package formatting and control files
11 | - filesystem layout
12 | - :term:`operating system ` design principles
13 | - maintainer scripts
14 | - inter-package relationships
15 | - shared library handling
16 |
17 | See the `Debian Policy Manual `_ for the latest version of the Debian policy.
18 |
19 | Policy conformance
20 | ------------------
21 |
22 | It's recommended but not mandatory that every :term:`source package ` should conform to the latest version of the Debian policy available at the time of the package’s last update.
23 |
24 | The ``Standards-Version`` field in the :file:`debian/control` file of the source package must be filled out to indicate the version of the Debian policy that the package complies with. Also, package maintainers must review policy changes before updating this field.
25 |
26 | :file:`debian/control` file
27 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~
28 |
29 | The :file:`debian/control` file defines key metadata for source packages and :term:`binary packages `. It resides in the root of the source package directory and is required for all source packages.
30 |
31 | This file consists of stanzas, which are sections of fields separated by empty lines. The first stanza defines the source package. Each following stanza describes a binary package built from that source package.
32 |
33 | Here are the required fields in the first stanza of the :file:`debian/control` file of the source package:
34 |
35 | ``Source``
36 | The name of the source package, which must be unique within the Debian archive.
37 |
38 | ``Maintainer``
39 | Name and email of the primary maintainer. This field is crucial for contacting the maintainer regarding issues, updates, or questions related to the package.
40 |
41 | ``Standards-Version``
42 | The version of the Standard the package complies with.
43 |
44 | Recommended fields in the first stanza of the :file:`debian/control` file include ``Section`` and ``Priority``.
45 |
46 | For more information on :file:`debian/control` files and their fields, see `Control files and their fields `_.
47 |
48 | ``Standards-Version`` field
49 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~
50 |
51 | The ``Standards-Version`` field in the :file:`debian/control` file indicates which version of the Debian policy the package has been reviewed against. The field must appear in the first stanza of the :file:`debian/control` file.
52 |
53 | The value of the field, which is the Debian policy version number, has four components:
54 |
55 | .. code-block:: text
56 |
57 | Standards-Version: ...
58 |
59 | Here is a breakdown of the components:
60 |
61 | * **Major version** (````): Incremented for significant policy changes requiring widespread updates.
62 | * **Minor version** (````): Changed for substantial but less disruptive updates.
63 | * **Major patch level** (````): Updated for any normative binding changes.
64 | * **Minor patch level** (````): Used for non-functional fixes like typos and clarifications.
65 |
66 | Only the first three components are significant. You may include or omit the fourth.
67 |
68 | When updating an existing package, only update the ``Standards-Version`` field after reviewing the differences between the old and new policy versions and updating the package if necessary.
69 |
70 | Upgrading checklist
71 | ~~~~~~~~~~~~~~~~~~~
72 |
73 | Before updating the ``Standards-Version`` field, follow these steps to ensure compliance:
74 |
75 | 1. Check the ``Standards-Version`` value in :file:`debian/control`.
76 | #. Review the changes introduced in newer versions. Refer to the `Upgrading checklist `_ section of the Debian Policy Manual for a summary of the changes made in each version.
77 | #. Review relevant sections of the policy based on listed changes and apply updates only when necessary.
78 | #. Test the package to confirm that it builds and behaves correctly with the new standard.
79 | #. Update the ``Standards-Version`` field in :file:`debian/control` file to the new version.
80 |
81 | Resources
82 | ---------
83 |
84 | - `Debian Policy Manual `_
85 |
--------------------------------------------------------------------------------
/docs/.sphinx/_static/furo_colors.css:
--------------------------------------------------------------------------------
1 | body {
2 | --color-code-background: #f8f8f8;
3 | --color-code-foreground: black;
4 | --code-font-size: 1rem;
5 | --font-stack: Ubuntu variable, Ubuntu, -apple-system, Segoe UI, Roboto, Oxygen, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif;
6 | --font-stack--monospace: Ubuntu Mono variable, Ubuntu Mono, Consolas, Monaco, Courier, monospace;
7 | --color-foreground-primary: #111;
8 | --color-foreground-secondary: var(--color-foreground-primary);
9 | --color-foreground-muted: #333;
10 | --color-background-secondary: #FFF;
11 | --color-background-hover: #f2f2f2;
12 | --color-brand-primary: #111;
13 | --color-brand-content: #06C;
14 | --color-api-background: #cdcdcd;
15 | --color-inline-code-background: rgba(0,0,0,.03);
16 | --color-sidebar-link-text: #111;
17 | --color-sidebar-item-background--current: #ebebeb;
18 | --color-sidebar-item-background--hover: #f2f2f2;
19 | --toc-font-size: var(--font-size--small);
20 | --color-admonition-title-background--note: var(--color-background-primary);
21 | --color-admonition-title-background--tip: var(--color-background-primary);
22 | --color-admonition-title-background--important: var(--color-background-primary);
23 | --color-admonition-title-background--caution: var(--color-background-primary);
24 | --color-admonition-title--note: #24598F;
25 | --color-admonition-title--tip: #24598F;
26 | --color-admonition-title--important: #C7162B;
27 | --color-admonition-title--caution: #F99B11;
28 | --color-highlighted-background: #EbEbEb;
29 | --color-link-underline: var(--color-background-primary);
30 | --color-link-underline--hover: var(--color-background-primary);
31 | --color-version-popup: #772953;
32 | }
33 |
34 | @media not print {
35 | body[data-theme="dark"] {
36 | --color-code-background: #202020;
37 | --color-code-foreground: #d0d0d0;
38 | --color-foreground-secondary: var(--color-foreground-primary);
39 | --color-foreground-muted: #CDCDCD;
40 | --color-background-secondary: var(--color-background-primary);
41 | --color-background-hover: #666;
42 | --color-brand-primary: #fff;
43 | --color-brand-content: #06C;
44 | --color-sidebar-link-text: #f7f7f7;
45 | --color-sidebar-item-background--current: #666;
46 | --color-sidebar-item-background--hover: #333;
47 | --color-admonition-background: transparent;
48 | --color-admonition-title-background--note: var(--color-background-primary);
49 | --color-admonition-title-background--tip: var(--color-background-primary);
50 | --color-admonition-title-background--important: var(--color-background-primary);
51 | --color-admonition-title-background--caution: var(--color-background-primary);
52 | --color-admonition-title--note: #24598F;
53 | --color-admonition-title--tip: #24598F;
54 | --color-admonition-title--important: #C7162B;
55 | --color-admonition-title--caution: #F99B11;
56 | --color-highlighted-background: #666;
57 | --color-link-underline: var(--color-background-primary);
58 | --color-link-underline--hover: var(--color-background-primary);
59 | --color-version-popup: #F29879;
60 | }
61 | @media (prefers-color-scheme: dark) {
62 | body:not([data-theme="light"]) {
63 | --color-code-background: #202020;
64 | --color-code-foreground: #d0d0d0;
65 | --color-foreground-secondary: var(--color-foreground-primary);
66 | --color-foreground-muted: #CDCDCD;
67 | --color-background-secondary: var(--color-background-primary);
68 | --color-background-hover: #666;
69 | --color-brand-primary: #fff;
70 | --color-brand-content: #06C;
71 | --color-sidebar-link-text: #f7f7f7;
72 | --color-sidebar-item-background--current: #666;
73 | --color-sidebar-item-background--hover: #333;
74 | --color-admonition-background: transparent;
75 | --color-admonition-title-background--note: var(--color-background-primary);
76 | --color-admonition-title-background--tip: var(--color-background-primary);
77 | --color-admonition-title-background--important: var(--color-background-primary);
78 | --color-admonition-title-background--caution: var(--color-background-primary);
79 | --color-admonition-title--note: #24598F;
80 | --color-admonition-title--tip: #24598F;
81 | --color-admonition-title--important: #C7162B;
82 | --color-admonition-title--caution: #F99B11;
83 | --color-highlighted-background: #666;
84 | --color-link-underline: var(--color-background-primary);
85 | --color-link-underline--hover: var(--color-background-primary);
86 | --color-version-popup: #F29879;
87 | }
88 | }
89 | }
90 |
--------------------------------------------------------------------------------
/docs/how-to/download-new-upstream-version.rst:
--------------------------------------------------------------------------------
1 | Download a new upstream version
2 | ===============================
3 |
4 | Once in a while you may need to download a new :term:`upstream ` release
5 | or check if a newer upstream release exists; for example:
6 |
7 | - When fixing a bug, to rule out that a more recent version may have already fixed the bug.
8 | - As a :term:`source package ` :term:`maintainer `, to check for,
9 | download, and package a newer upstream release.
10 |
11 | Most of the source packages contain a ``watch`` file in the ``debian``
12 | folder. This is a configuration file for the :manpage:`uscan(1)` utility which allows you to
13 | automatically search HTTP or FTP sites or :manpage:`git(1)` repositories
14 | for newly available updates of the upstream project.
15 |
16 | .. note::
17 | If the source package does not contain a :file:`debian/watch` file, there may be
18 | an explanation and instructions in the :file:`debain/README.source` or
19 | :file:`debian/README.debian` file (if available) that tell you how to proceed.
20 |
21 | Best practices
22 | --------------
23 |
24 | You should download upstream file(s) manually only if there is no automatic
25 | download mechanism and you can't find any download instructions.
26 |
27 | Remember that a package may get distributed to hundreds of thousands of users.
28 | Humans are the weakest link in this distribution chain, because we may
29 | accidentally miss or skip a verification step, misspell a :term:`URL`, copy the
30 | wrong URL or copy a URL only partially, etc.
31 |
32 | If you still have to download upstream file(s) manually make sure to
33 | verify :term:`Cryptographic Signatures ` (if available).
34 | The :term:`Signing Key` of the upstream project should be stored in the source
35 | package as :file:`debian/upstream/signing-key.asc` (if the upstream project
36 | has a signing key).
37 |
38 | :manpage:`uscan(1)` verifies downloads against this signing key
39 | automatically (if available).
40 |
41 | Download new upstream version (if available)
42 | --------------------------------------------
43 |
44 | Running :manpage:`uscan(1)` from the :term:`Root` of the :term:`Source Tree` will
45 | check if a newer upstream version exists and downloads it:
46 |
47 | .. code-block:: bash
48 |
49 | uscan
50 |
51 | If :manpage:`uscan(1)` could not find a newer upstream version it will
52 | return with the exit code `1` and print nothing to the :term:`Standard Output`.
53 |
54 | :manpage:`uscan(1)` reads the first entry in :file:`debian/changelog` to determine
55 | the name and version of the source package.
56 |
57 | You can always add the ``--verbose`` flag to see more information (e.g., which version
58 | :manpage:`uscan(1)` found):
59 |
60 | .. code-block:: bash
61 |
62 | uscan --verbose
63 |
64 | Check for new upstream version (no download)
65 | --------------------------------------------
66 |
67 | If you just want to check if a new update is available, but you don't want to download
68 | anything, you can run the :manpage:`uscan(1)` command with the ``--safe`` flag
69 | from the :term:`Root` of the source tree:
70 |
71 | .. code-block:: bash
72 |
73 | uscan --safe
74 |
75 | Force the download
76 | ------------------
77 |
78 | You can use the ``--force-download`` flag to download an upstream release
79 | from the upstream project, even if the upstream Release is up-to-date
80 | with the source package:
81 |
82 | .. code-block:: bash
83 |
84 | uscan --force-download
85 |
86 | Download the source of older versions from the upstream project
87 | ---------------------------------------------------------------
88 |
89 | If you want to download the source of a specific version from the
90 | upstream project you can use the ``--download-version`` flag.
91 |
92 | Basic syntax:
93 |
94 | .. code-block:: none
95 |
96 | uscan --download-version VERSION
97 |
98 | For example:
99 |
100 | .. code-block:: bash
101 |
102 | uscan --download-version '1.0'
103 |
104 | In the special case that you want to download the source for the
105 | current version of the source package from the upstream project
106 | you can use the ``--download-current-version`` flag instead, which parses the
107 | version to download from the first entry in :file:`debian/changelog` file:
108 |
109 | .. code:: bash
110 |
111 | uscan --download-current-version
112 |
113 | .. note::
114 |
115 | The ``--download-version`` and ``--download-current-version`` flags are
116 | both a :term:`best-effort` features of :manpage:`uscan(1)`.
117 |
118 | There are special cases where they do not work for technical reasons.
119 |
120 | .. note::
121 |
122 | In most cases you actually want to download the source from the :term:`Ubuntu Archive`
123 | and not re-download the source from the upstream project.
124 |
125 | :doc:`How to get the Source from the Archive? `
126 |
127 | Further Information
128 | -------------------
129 |
130 | - Manual page -- :manpage:`uscan(1)`
131 | - Debian wiki -- `debian/watch `_
132 | - Debian policy ``4.6.2.0`` -- `Upstream source location: debian/watch `_
133 |
--------------------------------------------------------------------------------
/docs/how-to/build-packages.rst:
--------------------------------------------------------------------------------
1 | Build packages
2 | ==============
3 |
4 | In Ubuntu, packages can be built in several ways, depending on the intended
5 | artifacts. We cover the following types of builds:
6 |
7 | * Source and binary (using ``sbuild`` for a clean environment)
8 | * Binary-only (using ``sbuild`` for a clean environment)
9 | * Source-only (using ``debuild``)
10 | * Binary-only (using ``debuild`` and installed build dependencies)
11 |
12 | (Many other backends are available, including an ``schroot``-based backend.)
13 |
14 | Only source uploads are permitted to PPAs or the archive. That
15 | being said, it is best practice to perform a local build and iron out any
16 | potential issues prior to uploading it to any archive.
17 |
18 |
19 | Prerequisites
20 | -------------
21 |
22 | .. code-block:: text
23 |
24 | $ sudo apt install sbuild debhelper ubuntu-dev-tools piuparts
25 |
26 | All of the following sections assume you have already fetched the packaging
27 | and are in the same directory as :file:`debian/`.
28 |
29 | For :manpage:`sbuild(1)`, follow the instructions on the Debian and Ubuntu
30 | sbuild pages as linked in the Resources section.
31 |
32 |
33 | ``sbuild``-based builds
34 | -----------------------
35 |
36 | This is the standard way of building a package for Ubuntu. All of the Debian
37 | and Ubuntu infrastructure use :manpage:`sbuild(1)`, so it is beneficial to
38 | learn how to use it. For more information on setting up :manpage:`sbuild(1)`,
39 | refer to the links in the Resources section.
40 |
41 | To do a binary-only build of a package using ``sbuild``, run:
42 |
43 | .. code-block:: text
44 |
45 | $ sbuild -c -[-shm]
46 |
47 | .. note::
48 |
49 | It is possible to use ``-d`` instead of ``-c``, but that causes the produced
50 | files to contain the entire chroot name (``-[-shm]``) instead
51 | of just ````. An example chroot name is ``noble-amd64-shm``.
52 |
53 | To explicitly run Lintian following the build:
54 |
55 | .. code-block:: text
56 |
57 | $ sbuild -c -[-shm] --run-lintian [--lintian-opts="-EvIiL +pedantic"]
58 |
59 | To build a package without running :manpage:`dh_clean(1)`, run:
60 |
61 | .. code-block:: text
62 |
63 | $ sbuild -c -[-shm] --no-clean-source
64 |
65 | To build both a binary *and* a source package with one ``sbuild`` run:
66 |
67 | .. code-block:: text
68 |
69 | $ sbuild -c -[-shm] -s
70 |
71 | .. note::
72 |
73 | Launchpad rejects uploads that contains both binaries and sources.
74 | However, this is required for uploads to the Debian NEW queue. That being
75 | said, uploads to Debian with binaries `do not migrate to Testing `_.
76 |
77 | Here is a complete, working example of running the ``autopkgtest`` following the build:
78 |
79 | .. code-block:: text
80 |
81 | $ sbuild -c noble-amd64-shm --run-autopkgtest \
82 | --autopkgtest-virt-server=qemu \
83 | --autopkgtest-virt-server-opt="/path/to/autopkgtest-noble-amd64.img" \
84 | --autopkgtest-opt="--apt-pocket=proposed=src:qt6-base" \
85 | --autopkgtest-opt="-U" --autopkgtest-opt="--ram-size=12000" \
86 | --autopkgtest-opt="--setup-commands='apt-get -y install aptitude \
87 | && aptitude -t noble-proposed -y install qt6-base-dev=6.8.1+dfsg-0ubuntu1'"
88 |
89 |
90 | Building with ``debuild``
91 | -------------------------
92 |
93 | :manpage:`debuild(1)` (short for :manpage:`dpkg-buildpackage(1)`) is
94 | another tool used to build Debian packages. It is part of the
95 | :manpage:`debhelper(7)` package and written in Perl.
96 |
97 | Ubuntu maintain its own version the ``debhelper`` package. Therefore,
98 | packages built on Debian may be slightly different than packages built on
99 | Ubuntu.
100 |
101 |
102 | Source-only builds
103 | ~~~~~~~~~~~~~~~~~~
104 |
105 | To build a source package *without* including the upstream tarball, run:
106 |
107 | .. code-block:: text
108 |
109 | $ debuild -S -d
110 |
111 | To build a source package *with* the upstream tarball, run:
112 |
113 | .. code-block:: text
114 |
115 | $ debuild -S -d -sa
116 |
117 | To build a source package without running Lintian, run:
118 |
119 | .. code-block:: text
120 |
121 | $ debuild --no-lintian -S -d
122 |
123 | .. note::
124 |
125 | The ``--no-lintian`` flag only works in this case if it is first.
126 |
127 | To build a source package without running :manpage:`dh_clean(1)`, run:
128 |
129 | .. code-block:: text
130 |
131 | $ debuild -S -d -nc
132 |
133 | .. note::
134 |
135 | This tends to fix failures regarding missing build dependencies.
136 |
137 | To build a source package without a cryptographic signature (not recommended), run:
138 |
139 | .. code-block:: text
140 |
141 | $ debuild -S -d -us -uc
142 |
143 |
144 | Local binary-only builds
145 | ~~~~~~~~~~~~~~~~~~~~~~~~
146 |
147 | This is really only useful for packages you need to test locally or
148 | packages with minimal build dependencies. Otherwise use :manpage:`sbuild(1)`.
149 |
150 | To do a binary-only build of a package, run:
151 |
152 | .. code-block:: text
153 |
154 | $ debuild -b
155 |
156 |
157 | Resources
158 | ---------
159 |
160 | * `Chapter 6. Building the package (Debian New Maintainers' Guide) `_
161 | * `SimpleSbuild (Ubuntu Wiki) `_
162 | * `sbuild (Debian Wiki) `_
163 |
--------------------------------------------------------------------------------
/README.rst:
--------------------------------------------------------------------------------
1 | The Ubuntu Packaging Guide
2 | --------------------------
3 |
4 | This guide is often one of the first things that a new Ubuntu contributor will
5 | look at. Helping make it better can have a big impact.
6 |
7 | The actual articles can be found under the ``docs/`` directory in rst files.
8 | Images can be placed in the ``docs/images/`` folder.
9 |
10 | The html, js and css files can be found under ``docs/_static``. The theme used
11 | in these docs is the "furo" theme, which has been modified to approach a more
12 | Ubuntu-esque appearance. The `furo documentation `_ has instructions on how to
13 | change most of the theme's functionality.
14 |
15 | If adding a new article, make sure to add it to the index page for the Diataxis
16 | section it belongs in. These indexes are in ``docs/`` and should be easy to
17 | locate. Place the file in the corresponding sub-folder in the ``docs/``
18 | directory, and your article should appear in both the Diataxis section page and
19 | the navigation menu on the left-hand-side of the screen.
20 |
21 | This project is licensed under the CC-BY-SA-3.0, the full text of which can be
22 | found in ``COPYING``.
23 |
24 | How to build this documentation
25 | -------------------------------
26 | Find the full documentation for the `Ubuntu Packaging Guide `_ at "Read the Docs".
27 |
28 | To build this documentation on your own machine, first clone this
29 | repository: ::
30 |
31 | git clone git@github.com:canonical/ubuntu-packaging-guide.git
32 |
33 | Navigate to the ``docs/`` folder, which is inside the root directory. Now
34 | run: ::
35 |
36 | make install
37 |
38 | This will install the necessary packages and other dependencies, and set up
39 | the Python 3 virtual environment. Finally, use the ``make run`` command to
40 | build the documentation, serve it, and watch for changes. Other options are
41 | available and are printed to the terminal when you run ``make install``. You
42 | can also refer to ``make help`` for a full and complete list of options.
43 |
44 | Files are written to the ``_build`` directory.
45 |
46 | We use the autobuild module so that any edits you make (and save) as you work
47 | will be applied and the documentation refreshed immediately.
48 |
49 | Contributing
50 | ------------
51 |
52 | We welcome everyone who wants to improve the Ubuntu documentation!
53 | Whether you've found a typo, have a suggestion for improving existing
54 | content, or want to add new content, we'd love to hear from you.
55 |
56 | You can find this ``git`` repository on `GitHub `_
57 | and `Launchpad `_.
58 |
59 | To contribute, simply choose the platform you prefer:
60 |
61 | GitHub
62 | ^^^^^^
63 |
64 | * `Open an issue and describe your problem `_
65 | * `Ask a question or start a discussion `_
66 | * `Open a pull request to submit your fix `_
67 |
68 | Launchpad
69 | ^^^^^^^^^
70 |
71 | * `Open a bug ticket `_
72 |
73 | We'll review your contribution as soon as possible, but please note that
74 | our Ubuntu maintainers often have full inboxes, so we may not get to your
75 | message immediately.
76 |
77 | **Note:** We are currently in a transition phase from ``bazaar`` to ``git``.
78 | If you spot any instructions to use ``bazaar`` to contribute, bringing them to
79 | our attention so we can fix them is a great way to start contributing!
80 |
81 | Sphinx & reStructuredText
82 | -------------------------
83 |
84 | The guide is built using `Sphinx `_. Articles should
85 | be written in reStructuredText. The following links might be helpful:
86 |
87 | * https://docutils.sourceforge.io/docs/user/rst/quickstart.html
88 | * https://docutils.sourceforge.io/docs/user/rst/quickref.html
89 |
90 | Adding a new Sphinx extension
91 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
92 |
93 | In general, there are two places you will need to update to add new extensions.
94 |
95 | * ``docs/conf.py`` - add the name of the extension to the extensions config
96 | parameter
97 | * ``docs/.sphinx/requirements.txt`` - add the name of the extension to the
98 | bottom of the list
99 |
100 | The documentation for most Sphinx extensions will tell you what text to add
101 | to the ``conf.py`` file. ::
102 |
103 | extensions = [
104 | 'm2r2',
105 | 'sphinx_copybutton',
106 | 'sphinx_design',
107 | ]
108 |
109 | Translating
110 | -----------
111 |
112 | We use Sphinx l10n module and Gettext for translating Ubuntu Packaging Guide.
113 |
114 | Some notes about translating the guide:
115 |
116 | - Some formatting is part of reStructuredText and should not be changed,
117 | including emphasis (which uses asterisks or underscores), paragraph ending
118 | before a code block (``::``) and double backtick quotes (``````).
119 |
120 | - This guide uses email-style reStructuredText links. If you see a link in
121 | the text like::
122 |
123 | `Translatable link text `_
124 |
125 | Then replace the link text with your translations, but keep the
126 | LinkReference unchanged (even if it is in English). The same applies
127 | if URL is used instead of LinkReference.
128 |
129 | To test your translation, use ``make BUILDER-LANGUAGE`` command (for example,
130 | ``make html-it`` will build HTML docs in Italian language).
131 |
--------------------------------------------------------------------------------
/docs/doc-cheat-sheet.rst:
--------------------------------------------------------------------------------
1 | :orphan:
2 |
3 | .. _cheat-sheet:
4 |
5 | reStructuredText cheat sheet
6 | ============================
7 |
8 | This file contains the syntax for commonly used reST markup.
9 | Open it in your text editor to quickly copy and paste the markup you need.
10 |
11 | See the `reStructuredText style guide `_ for detailed information and conventions.
12 |
13 | Also see the `Sphinx reStructuredText Primer `_ for more details on reST, and the `Canonical Documentation Style Guide `_ for general style conventions.
14 |
15 | H2 heading
16 | ----------
17 |
18 | H3 heading
19 | ~~~~~~~~~~
20 |
21 | H4 heading
22 | ^^^^^^^^^^
23 |
24 | H5 heading
25 | ..........
26 |
27 | Inline formatting
28 | -----------------
29 |
30 | - :guilabel:`UI element`
31 | - ``code``
32 | - :file:`file path`
33 | - :command:`command`
34 | - :kbd:`Key`
35 | - *Italic*
36 | - **Bold**
37 |
38 | Code blocks
39 | -----------
40 |
41 | Start a code block::
42 |
43 | code:
44 | - example: true
45 |
46 | .. code::
47 |
48 | # Demonstrate a code block
49 | code:
50 | - example: true
51 |
52 | .. code:: yaml
53 |
54 | # Demonstrate a code block
55 | code:
56 | - example: true
57 |
58 | .. _a_section_target:
59 |
60 | Links
61 | -----
62 |
63 | - `Canonical website `_
64 | - `Canonical website`_ (defined in ``reuse/links.txt`` or at the bottom of the page)
65 | - https:\ //canonical.com/
66 | - :ref:`a_section_target`
67 | - :ref:`Link text `
68 | - :doc:`index`
69 | - :doc:`Link text `
70 |
71 |
72 | Navigation
73 | ----------
74 |
75 | Use the following syntax::
76 |
77 | .. toctree::
78 | :hidden:
79 |
80 | sub-page1
81 | sub-page2
82 |
83 |
84 | Lists
85 | -----
86 |
87 | 1. Step 1
88 |
89 | - Item 1
90 |
91 | * Sub-item
92 | - Item 2
93 |
94 | i. Sub-step 1
95 | #. Sub-step 2
96 | #. Step 2
97 |
98 | a. Sub-step 1
99 |
100 | - Item
101 | #. Sub-step 2
102 |
103 | Term 1:
104 | Definition
105 | Term 2:
106 | Definition
107 |
108 | Tables
109 | ------
110 |
111 | +----------------------+------------+
112 | | Header 1 | Header 2 |
113 | +======================+============+
114 | | Cell 1 | Cell 2 |
115 | | | |
116 | | Second paragraph | |
117 | +----------------------+------------+
118 | | Cell 3 | Cell 4 |
119 | +----------------------+------------+
120 |
121 | +----------------------+------------------+
122 | | :center:`Header 1` | Header 2 |
123 | +======================+==================+
124 | | Cell 1 | Cell 2 |
125 | | | |
126 | | Second paragraph | |
127 | +----------------------+------------------+
128 | | Cell 3 | :center:`Cell 4` |
129 | +----------------------+------------------+
130 |
131 | .. list-table::
132 | :header-rows: 1
133 |
134 | * - Header 1
135 | - Header 2
136 | * - Cell 1
137 |
138 | Second paragraph
139 | - Cell 2
140 | * - Cell 3
141 | - Cell 4
142 |
143 | .. rst-class:: align-center
144 |
145 | +----------------------+------------+
146 | | Header 1 | Header 2 |
147 | +======================+============+
148 | | Cell 1 | Cell 2 |
149 | | | |
150 | | Second paragraph | |
151 | +----------------------+------------+
152 | | Cell 3 | Cell 4 |
153 | +----------------------+------------+
154 |
155 | .. list-table::
156 | :header-rows: 1
157 | :align: center
158 |
159 | * - Header 1
160 | - Header 2
161 | * - Cell 1
162 |
163 | Second paragraph
164 | - Cell 2
165 | * - Cell 3
166 | - Cell 4
167 |
168 | Notes
169 | -----
170 |
171 | .. note::
172 | A note.
173 |
174 | .. tip::
175 | A tip.
176 |
177 | .. important::
178 | Important information
179 |
180 | .. caution::
181 | This might damage your hardware!
182 |
183 | Images
184 | ------
185 |
186 | .. image:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png
187 |
188 | .. figure:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png
189 | :width: 100px
190 | :alt: Alt text
191 |
192 | Figure caption
193 |
194 | Reuse
195 | -----
196 |
197 | .. |reuse_key| replace:: This is **included** text.
198 |
199 | |reuse_key|
200 |
201 | .. include:: index.rst
202 | :start-after: include_start
203 | :end-before: include_end
204 |
205 | Tabs
206 | ----
207 |
208 | .. tabs::
209 |
210 | .. group-tab:: Tab 1
211 |
212 | Content Tab 1
213 |
214 | .. group-tab:: Tab 2
215 |
216 | Content Tab 2
217 |
218 |
219 | Glossary
220 | --------
221 |
222 | .. glossary::
223 |
224 | example term
225 | Definition of the example term.
226 |
227 | :term:`example term`
228 |
229 | More useful markup
230 | ------------------
231 |
232 | - .. versionadded:: X.Y
233 | - | Line 1
234 | | Line 2
235 | | Line 3
236 | - .. This is a comment
237 | - :abbr:`API (Application Programming Interface)`
238 |
239 | ----
240 |
241 | Custom extensions
242 | -----------------
243 |
244 | Related links at the top of the page::
245 |
246 | :relatedlinks: https://github.com/canonical/lxd-sphinx-extensions, [RTFM](https://www.google.com)
247 | :discourse: 12345
248 |
249 | Terms that should not be checked by the spelling checker: :spellexception:`PurposelyWrong`
250 |
251 | A terminal view with input and output:
252 |
253 | .. terminal::
254 | :input: command
255 | :user: root
256 | :host: vampyr
257 |
258 | the output
259 |
260 | A link to a YouTube video:
261 |
262 | .. youtube:: https://www.youtube.com/watch?v=iMLiK1fX4I0
263 | :title: Demo
264 |
265 |
266 |
267 | .. LINKS
268 | .. _Canonical website: https://canonical.com/
269 |
--------------------------------------------------------------------------------
/docs/explanation/upstream-and-downstream.rst:
--------------------------------------------------------------------------------
1 | Upstream and downstream
2 | =======================
3 |
4 | An :term:`Ubuntu` installation consists of :term:`packages ` - copied
5 | and unpacked onto the target machine. The Ubuntu project packages, distributes
6 | and maintains software of thousands of :term:`open source `
7 | projects for users, ready to install. The collection of Ubuntu packages is
8 | derived from the collection of packages maintained by the community-driven
9 | :term:`Debian` project.
10 |
11 | An important duty of an Ubuntu package :term:`Maintainer` is to
12 | collaborate with the open source projects the Ubuntu packages are derived from --
13 | especially with Debian. We do this by keeping the Ubuntu copies of packages
14 | up-to-date and by sharing improvements made in Ubuntu back up to Debian.
15 |
16 | Terminology
17 | -----------
18 |
19 | In the context of open source software development, the analogy of a stream
20 | that carries modifications, improvements, and code is used. It describes the
21 | relationship and direction of changes made between projects. This stream
22 | originates (upwards) from the original project (and related entities like
23 | :term:`Source Code`, authors, and maintainers) and flows downwards to projects
24 | (and associated entities) that depend on it.
25 |
26 | Ubuntu delta
27 | ~~~~~~~~~~~~
28 |
29 | Ubuntu delta (noun):
30 | A modification to an Ubuntu package that is derived from a Debian
31 | package.
32 |
33 | .. _Upstream:
34 |
35 | Upstream
36 | ~~~~~~~~
37 |
38 | .. _upstream_noun:
39 |
40 | Upstream (noun):
41 | A software project (and associated entities) that another software project
42 | depends on either directly or indirectly.
43 |
44 | *Examples*:
45 | - Debian is the upstream of Ubuntu.
46 | - Upstream is not interested in the patch.
47 |
48 | *Usage note*:
49 | - There can be many layers. For example, **Kubuntu** is a
50 | :term:`flavour ` of Ubuntu, therefore Ubuntu and
51 | Debian are both upstreams of Kubuntu.
52 | - The adjective/adverb form is much more commonly used.
53 |
54 | .. _upstream_adjective_adverb:
55 |
56 | Upstream (adjective, adverb):
57 | Something (usually a code modification like a :term:`patch `) that
58 | flows in the direction or is relative to a software project closer to the
59 | original software project.
60 |
61 | *Examples*:
62 | - Debian is the upstream project of Ubuntu.
63 | - There is a new upstream release.
64 | - A pull request was created upstream.
65 | - A bug was patched upstream.
66 |
67 | .. _upstream_verb:
68 |
69 | upstream (verb):
70 | Sending something (usually a patch) upstream that originated from a
71 | :term:`Fork` or project that depended on the upstream project.
72 |
73 | *Examples*:
74 | - We upstreamed the patch.
75 | - Can you upstream the bugfix?
76 |
77 | .. _Downstream:
78 |
79 | Downstream
80 | ~~~~~~~~~~
81 |
82 | Downstream (noun):
83 | Similar to :ref:`upstream_noun` A software project(s) (and associated
84 | entities) that depend on another software project either directly or
85 | indirectly.
86 |
87 | *Example*:
88 | - Ubuntu is a downstream of Debian and there are many downstreams
89 | of Ubuntu.
90 |
91 | *Usage note*:
92 | - The :ref:`adjective/adverb form ` is
93 | much more commonly used.
94 | - There can be many layers. For example, **Kubuntu** is a flavour of
95 | Ubuntu, therefore Kubuntu and Ubuntu are both downstreams of Debian.
96 |
97 | .. _downstream_adjective_adverb:
98 |
99 | Downstream (adjective, adverb):
100 | Similar to :ref:`upstream_adjective_adverb` Something (usually a code
101 | modification like a patch) that flows in the direction or is relative to a
102 | software project farther away from the original software project.
103 |
104 | *Examples*:
105 | - Ubuntu is a downstream project of Debian.
106 | - The bug is already patched downstream.
107 | - The bug was reported by a downstream user.
108 | - Downstream maintainers have submitted a bugfix.
109 | - The change may affect downstream users.
110 |
111 | Downstream (verb):
112 | Similar to :ref:`upstream_verb` Sending something (usually a patch)
113 | downstream that originated from an upstream project.
114 |
115 | *Example*:
116 | - We downstreamed the patch.
117 |
118 | Why do we upstream changes?
119 | ---------------------------
120 |
121 | .. note::
122 | The following list does not aim for completeness. There are plenty of other
123 | good arguments for why changes should be upstreamed.
124 |
125 | - **Decreased maintenance complexity**: Think of any Ubuntu package derived
126 | from a Debian package that carries a :term:`delta `. Every time
127 | the Debian package gets updated, the Ubuntu package may be subject to a
128 | :term:`merge conflict ` when the changes to the Debian package
129 | get applied to the Ubuntu package. By upstreaming changes we reduce the
130 | maintenance cost to resolve merge conflicts when they occur.
131 | - **Quality assurance and security**: Any changes that get upstreamed will also
132 | be subject to the quality assurance of the upstream project and the testing
133 | coverage that the user base of the upstream project provides. This increases
134 | the likelihood of discovering regressions/bugs/unwanted behaviour (especially
135 | security-related bugs). Also, be aware that an unpatched
136 | :term:`security vulnerability ` in any
137 | system could lead to the indirect exposure of other systems.
138 | - **Mutual benefit**: By syncing the Debian packages into the Ubuntu package
139 | collection, Ubuntu benefits from the upstream maintenance work. In exchange,
140 | Ubuntu Maintainers upstream changes to Debian. This results in a win-win
141 | situation where both parties benefit from working together.
142 |
143 |
--------------------------------------------------------------------------------
/docs/explanation/launchpad.rst:
--------------------------------------------------------------------------------
1 | Launchpad
2 | =========
3 |
4 | Launchpad is a software collaboration and hosting platform similar to platforms
5 | like `GitHub`_. Launchpad is also the platform where the :term:`Ubuntu` project lives.
6 | This is one of the major differences between the Ubuntu and :term:`Debian`
7 | infrastructure.
8 |
9 | .. note::
10 |
11 | Although the Ubuntu project is probably the largest user base of Launchpad,
12 | Launchpad can be used by anyone.
13 |
14 | Launchpad features, among others, are:
15 |
16 | - **Bugs**: :term:`Bug Tracking System`
17 | - **Code**: :term:`source code ` hosting with :term:`Git` or :term:`Bazaar`,
18 | :term:`version control ` and :term:`code review ` features
19 | - **Answers**: community support site and knowledge base
20 | - **Translations**: collaboration platform for localising software
21 | - **Blueprints**: feature planning and specification tracking
22 | - Ubuntu :term:`package ` building and hosting
23 | - Team/Group management
24 |
25 | While platforms like GitHub put users and groups at the top level, Launchpad
26 | puts projects at the top level. If you take Ubuntu as an example, you can
27 | see that you can access it at the top level: `https://launchpad.net/ubuntu`.
28 | Users and groups begin with a ``~``, for instance `https://launchpad.net/~ubuntu-foundations-team`.
29 |
30 | Why not use platforms like GitHub?
31 | ----------------------------------
32 |
33 | Although Launchpad's :term:`UI` and :term:`UX` are a bit dated, Launchpad offers an
34 | unparalleled Ubuntu package building and hosting infrastructure that
35 | no other platform offers. Even simple requirements like building for architectures
36 | like :term:`PowerPC`, :term:`s390x`, or :term:`RISC-V` can not be fulfilled by GitHub
37 | or similar platforms.
38 |
39 | Personal Package Archive (PPA)
40 | ------------------------------
41 |
42 | Launchpad PPA repositories allow you to build installable Ubuntu packages for multiple
43 | :term:`architectures ` and to host them in your own software
44 | :term:`repository `.
45 |
46 | Using a PPA is straightforward; you don't need the approval of anyone, therefore users
47 | have to enable it manually. See how to :ref:`InstallPackagesFromPPA`.
48 |
49 | This is useful when you want to test a change, or to show others that a change
50 | builds successfully or is installable. Some people have special permission to
51 | trigger the :term:`autopkgtests ` for packages in a PPA.
52 |
53 | .. tip::
54 |
55 | You can ask in the :term:`IRC` channel ``#ubuntu-devel`` if someone can trigger
56 | autopkgtests in your PPA if you don't have the permission.
57 |
58 | git-based workflow for the development of Ubuntu source packages
59 | ----------------------------------------------------------------
60 |
61 | Launchpad hosts a :term:`git-ubuntu` importer service that maintains
62 | a view of the entire packaging version history of Ubuntu :term:`source packages ` using
63 | git repositories with a common branching and tagging scheme. The git-ubuntu
64 | :term:`CLI` provides tooling and automation that understands these repositories
65 | to make the development of Ubuntu itself easier.
66 |
67 | You can see the web-view of these repositories when you click on the "Code" tab
68 | of any source package on Launchpad, for example, in the
69 | `"hello" source package `_ as
70 | shown in the following screenshot:
71 |
72 | .. image:: ../images/explanation/launchpad/GitUbuntuRepositoryOfTheHelloPackage.png
73 | :align: center
74 | :width: 35 em
75 | :alt: Screenshot of the Launchpad Code page for the hello source package with an arrow pointing to the Code tab.
76 |
77 | Text markup
78 | -----------
79 |
80 | Launchpad has some markup features that you can use when you e.g. report bugs, write comments, create merge proposals.
81 |
82 | See the :doc:`/reference/launchpad-text-markup` reference for more details.
83 |
84 | Getting help
85 | ------------
86 |
87 | If you need help with Launchpad you can choose any of the following methods:
88 |
89 | IRC chat rooms
90 | ~~~~~~~~~~~~~~
91 |
92 | On the ``irc.libera.chat`` :term:`IRC` server you will find the ``#launchpad`` channel, where you
93 | can ask the Launchpad team and the Ubuntu community for help.
94 |
95 | Mailing lists
96 | ~~~~~~~~~~~~~
97 |
98 | If you prefer to ask for help via email, you can write to the
99 | `launchpad-users `_
100 | mailing list (``launchpad-users@lists.launchpad.net``).
101 |
102 | Ask a question
103 | ~~~~~~~~~~~~~~
104 |
105 | As mentioned above, Launchpad has a `community FAQ feature `_
106 | (called "Answers") where
107 | you can see other people's questions or ask one yourself. Use can use the *Answers*
108 | feature of the Launchpad project on Launchpad itself.
109 |
110 | Report a bug
111 | ~~~~~~~~~~~~
112 |
113 | If you encounter any bug related to Launchpad, you can submit a bug report to the
114 | :term:`Bug Tracking System` of the Launchpad project `on Launchpad itself `_.
115 |
116 | Staging environment
117 | -------------------
118 |
119 | Before new features are deployed to the production environment they get
120 | `deployed to a staging environment `_ where
121 | the changes can get tested.
122 |
123 | You can use the staging environment, to try out Launchpad features.
124 |
125 | API
126 | ---
127 |
128 | Launchpad has a web :term:`API` that you can use to interact with its services.
129 | This makes it easy for developer communities like Ubuntu's to
130 | automate specific workflows.
131 |
132 | You can find the reference `documentation for the web API `_ on Launchpad.
133 |
134 | The Launchpad team even created an :term:`open source `
135 | Python library, `launchpadlib `_.
136 |
137 | Resources
138 | ---------
139 |
140 | - `Launchpad home page `_
141 | - `The Launchpad software project on Launchpad itself `_
142 | - `Launchpad bug tracker `_
143 | - `Launchpad questions and answers `_
144 | - `Launchpad wiki `_
145 | - `Launchpad development wiki `_
146 | - `Launchpad blog `_
147 |
--------------------------------------------------------------------------------
/docs/index.rst:
--------------------------------------------------------------------------------
1 | Ubuntu Packaging Guide
2 | ======================
3 |
4 | Welcome to the Ubuntu Packaging and Development Guide!
5 |
6 | This is the official place for learning all about Ubuntu Development and
7 | packaging. After reading this guide you will have:
8 |
9 | * Heard about the most important players, processes and tools in
10 | Ubuntu development,
11 | * Your development environment set up correctly,
12 | * A better idea of how to join our community,
13 | * Fixed an actual Ubuntu bug as part of the tutorials.
14 |
15 | Ubuntu is not only a free and open source operating system, its platform is
16 | also open and developed in a transparent fashion. The source code for every
17 | single component can be obtained easily and every single change to the Ubuntu
18 | platform can be reviewed.
19 |
20 | This means you can actively get involved in improving it and the community of
21 | Ubuntu platform developers is always interested in helping peers getting
22 | started.
23 |
24 | Ubuntu is also a community of great people who believe in free software and
25 | that it should be accessible for everyone. Its members are welcoming and want
26 | you to be involved as well. We want you to get involved, to ask questions, to
27 | make Ubuntu better together with us.
28 |
29 | -----
30 |
31 | In this documentation
32 | ---------------------
33 |
34 | .. toctree::
35 | :hidden:
36 | :titlesonly:
37 |
38 | tutorial/_index
39 | how-to/_index
40 | explanation/_index
41 | reference/_index
42 | contribute
43 |
44 | .. grid:: 1 1 2 2
45 | :gutter: 3
46 |
47 | .. grid-item-card:: **Tutorial**
48 | :link: tutorial/_index
49 | :link-type: doc
50 |
51 | Get started - a hands-on introduction to the Ubuntu Packaging Guide for
52 | new users
53 |
54 | .. grid-item-card:: **How-to guides**
55 | :link: how-to/_index
56 | :link-type: doc
57 |
58 | Step-by-step guides covering key operations and common tasks
59 |
60 | .. grid-item-card:: **Explanation**
61 | :link: explanation/_index
62 | :link-type: doc
63 |
64 | Discussion and clarification of key topics
65 |
66 | .. grid-item-card:: **Reference**
67 | :link: reference/_index
68 | :link-type: doc
69 |
70 | Technical information - specifications, APIs, architecture
71 |
72 | Project and community
73 | ---------------------
74 |
75 | The Ubuntu Packaging Guide is an open source project that warmly welcomes
76 | community projects, contributions, suggestions, fixes and constructive feedback.
77 | In a project where thousands of lines of code are changed, lots of decisions
78 | are made and hundreds of people interact every day, it is important to
79 | communicate effectively.
80 |
81 | Read our `Code of Conduct`_ to get started. If you run into problems, don't panic!
82 | The following communication channels are there to help you.
83 |
84 | .. tip::
85 | It is encouraged for you to use the same nickname (a known identity or your
86 | real name) across all the following communication channels, so that your
87 | Ubuntu developer colleagues will be able to get to know you better.
88 |
89 | Launchpad:
90 | ~~~~~~~~~~
91 |
92 | `Launchpad`_ is the general development platform where Ubuntu itself and most of
93 | Ubuntu related software projects live. It is the place where bugs are tracked,
94 | source code is stored, tracked, get built, tested and much more.
95 |
96 | We will go into more detail in the following articles. For now, you can think of
97 | Launchpad as a platform like GitHub, GitLab or BitBucket.
98 |
99 | IRC channels:
100 | ~~~~~~~~~~~~~
101 | For real-time discussions, please connect to ``irc.libera.chat`` and join one or
102 | any of the `IRC channels`_. You may find especially these channels useful in the beginning:
103 |
104 | * ``#ubuntu-devel``, for general development discussion
105 | * ``#ubuntu-motu``, for :term:`Masters of the Universe` (:term:`MOTU`) team discussion and
106 | generally getting help.
107 | * ``#ubuntu-meeting``, meetings are held here by various Ubuntu teams and everyone
108 | is welcome to participate.
109 |
110 | You can follow these `instructions`_ on how to connect to ``irc.libera.chat``.
111 | Also, when you join ``irc.libera.chat`` for the first time, you should follow the
112 | `instructions to register a nickname`_ and register a nickname. If you don't register it,
113 | someone else may end up registering the nickname you want/used.
114 |
115 | .. note::
116 | Certain channels even require you to register before you can write in them.
117 |
118 | Discourse:
119 | ~~~~~~~~~~
120 | The `Ubuntu Discourse `_ instance is a meeting
121 | point for the Ubuntu community and a forum about general Ubuntu development
122 | where you can find discussions, announcements, team updates, documentation and
123 | much more.
124 |
125 | Feel free to introduce yourself `here `_.
126 |
127 | Mailing lists:
128 | ~~~~~~~~~~~~~~
129 | For long-lived discussions or announcements you can subscribe/write to any of
130 | the `Ubuntu mailing lists `_. You may find especially
131 | these :term:`Mailing Lists ` useful in the beginning:
132 |
133 | * https://lists.ubuntu.com/mailman/listinfo/ubuntu-devel-announce
134 | (announce-only, the most important development announcements go here)
135 | * https://lists.ubuntu.com/mailman/listinfo/ubuntu-devel
136 | (general Ubuntu development discussion)
137 | * https://lists.ubuntu.com/mailman/listinfo/ubuntu-motu
138 | (MOTU Team discussion, get help with packaging)
139 |
140 | .. note::
141 | When you subscribe to :term:`Mailing Lists `, expect to receive a lot of emails.
142 | A good way to manage these is to create email filters. For example,
143 | the `bug mailing lists `_ generate a high
144 | volume of emails and using the `custom email headers `_
145 | to filter them can help.
146 |
147 | -----
148 |
149 | We are always looking to improve this guide. If you find any problems or have
150 | some suggestions, use the **Give feedback** button at the top of any page to
151 | open a GitHub issue or directly contribute by submitting a pull request to the
152 | `source`_ repository.
153 |
154 | Further reading
155 | ---------------
156 |
157 | You can read this guide offline in different formats, if you install one of
158 | the `binary packages `_.
159 |
160 | If you want to learn more about building Debian packages, here are some Debian
161 | resources you may find useful:
162 |
163 | * `How to package for Debian `_
164 | * `Debian Policy Manual `_
165 | * `Debian New Maintainers' Guide `_ — available in many languages
166 | * `Packaging tutorial `_ (also available as a `package `_)
167 | * `Guide for Packaging Python Modules `_
168 |
169 | .. Links:
170 | .. _Code of Conduct: https://ubuntu.com/community/code-of-conduct
171 | .. _IRC channels: https://wiki.ubuntu.com/IRC/ChannelList
172 | .. _BinPkgs: https://launchpad.net/ubuntu/+source/ubuntu-packaging-guide
173 | .. _HowToPackage: https://wiki.debian.org/HowToPackageForDebian
174 | .. _Policy: http://www.debian.org/doc/debian-policy/
175 | .. _NewMaintGuide: http://www.debian.org/doc/manuals/maint-guide/
176 | .. _PkgTutorial: http://www.debian.org/doc/manuals/packaging-tutorial/
177 | .. _PkgTutorialPkg: https://launchpad.net/ubuntu/+source/packaging-tutorial
178 | .. _PythonModules: https://wiki.debian.org/Python/LibraryStyleGuide
179 | .. _source: https://github.com/canonical/ubuntu-packaging-guide
180 | .. _Masters of the Universe: https://wiki.ubuntu.com/MOTU
181 | .. _instructions: https://libera.chat/guides/connect
182 | .. _instructions to register a nickname: https://libera.chat/guides/registration
183 |
--------------------------------------------------------------------------------
/docs/reference/patchfile-headers.rst:
--------------------------------------------------------------------------------
1 | DEP 3 -- Patch file headers
2 | ===========================
3 |
4 | This article lists and briefly explains standard fields of the
5 | `Debian Enhancement Proposal 3 Specification (DEP-3) -- Patch Tagging Guidelines `_
6 | for ``.patch`` file headers and also shows :ref:`SampleDEP3CompliantHeaders`.
7 |
8 | Standard fields
9 | ---------------
10 |
11 | ``Description`` or ``Subject`` |required|
12 | This obligatory field contains at least a short description on the first
13 | line. When ``Subject`` is used, it is expected that the long description is
14 | outside of the structured fields. With ``Description`` it is possible to
15 | embed them in the field using continuation lines.
16 |
17 | In both cases, the long description allows for a more verbose explanation
18 | of the patch and its history.
19 |
20 | This field should explain why the patch is vendor-specific (e.g., branding patch)
21 | when that is the case. If the patch has been submitted :term:`upstream` but
22 | has been rejected, the description should also document why it's kept and what
23 | were the reasons for the reject.
24 |
25 | It's recommended to keep each line shorter than 80 characters.
26 |
27 | ``Origin`` |required|
28 | .. note::
29 | If the ``Author`` field is present, the ``Origin`` field can be omitted and it's
30 | assumed that the patch comes from its author.
31 |
32 | This field should document the origin of the patch. In most cases, it should be a
33 | simple URL. For patches backported/taken from upstream, it should point into the
34 | upstream :term:`VCS` web interface when possible, otherwise it can simply list the relevant
35 | commit identifier (it should be prefixed with "commit:" in that case).
36 | For other cases, one should simply indicate the URL where the patch was taken from
37 | (mailing list archives, distribution :term:`bug tracking system`, etc.) when possible.
38 |
39 | The field can be optionally prefixed with a single keyword followed by a comma and a
40 | space to categorize the origin. The allowed keywords are:
41 |
42 | - ``upstream`` in the case of a patch cherry-picked from the upstream VCS,
43 | - ``backport`` in the case of an upstream patch that had to be modified to apply on the current version,
44 | - ``vendor`` for a patch created by Debian or another distribution vendor, or
45 | - ``other`` for all other kind of patches.
46 |
47 | In general, a user-created patch grabbed from a :term:`Bug Tracking System` should be
48 | categorized as `other`. When copying a patch from another vendor, the meta-information
49 | (and hence this field) should be kept if present, or created if necessary with a
50 | `vendor` origin.
51 |
52 | ``Bug-`` or ``Bug`` |optional|
53 | It contains one URL pointing to the related bug (possibly fixed by the patch).
54 | The ``Bug`` field is reserved for the bug URL of the upstream bug tracker.
55 | Those fields can be used multiple times if several bugs are concerned.
56 |
57 | The ```` name is explicitly encoded in the field name so that vendors
58 | can share patches among them without having to update the meta-information in
59 | most cases. The upstream bug URL is special cased because it's the central point
60 | of cooperation and it must be easily distinguishable among all the bug URLs.
61 |
62 | ``Forwarded`` |optional|
63 | Any value other than ``no`` or ``not-needed`` means that the patch has been
64 | forwarded upstream. Ideally the value is an URL proving that it has been
65 | forwarded and where one can find more information about its inclusion status.
66 |
67 | If the field is missing, its implicit value is ``yes`` if the ``Bug`` field is
68 | present, otherwise it's ``no``. The field is really required only if the patch
69 | is vendor specific, in that case its value should be ``not-needed`` to indicate
70 | that the patch must not be forwarded upstream (whereas ``no`` simply means that
71 | it has not yet been done).
72 |
73 | ``Author`` or ``From`` |optional|
74 | This field can be used to record the name and email of the patch author
75 | (e.g., ``John Bear ``). Its usage is recommended when the patch
76 | author did not add copyright notices for his work in the patch itself.
77 | It's also a good idea to add this contact information when the patch needs to be
78 | maintained over time because it has very little chance of being integrated upstream.
79 |
80 | This field can be used multiple times if several people authored the patch.
81 |
82 | ``Reviewed-by`` or ``Acked-by`` |optional|
83 | This field can be used to document the fact that the patch has been reviewed and
84 | approved by someone. It should list their name and email in the standard format
85 | (e.g., ``John Bear ``).
86 |
87 | This field can be used multiple times if several people reviewed the patch.
88 |
89 | ``Last-Update`` |optional|
90 | This field can be used to record the date when the meta-information was last updated.
91 | It should use the ISO date format ``YYYY-MM-DD``.
92 |
93 | ``Applied-Upstream`` |optional|
94 | This field can be used to document the fact that the patch has been applied upstream.
95 |
96 | It may contain the upstream version expected to contain this patch, or the URL
97 | or commit identifier of the upstream commit (with commit identifiers prefixed with
98 | ``commit:``, as in the ``Origin`` field), or both separated by a comma and a space.
99 |
100 | .. _SampleDEP3CompliantHeaders:
101 |
102 | Sample DEP-3 compliant headers
103 | ------------------------------
104 |
105 | A patch cherry-picked from upstream:
106 |
107 | .. code-block:: none
108 |
109 | From: Ulrich Drepper
110 | Subject: Fix regex problems with some multi-bytes characters
111 |
112 | * posix/bug-regex17.c: Add testcases.
113 | * posix/regcomp.c (re_compile_fastmap_iter): Rewrite COMPLEX_BRACKET
114 | handling.
115 |
116 | Origin: upstream, http://sourceware.org/git/?p=glibc.git;a=commitdiff;h=bdb56bac
117 | Bug: http://sourceware.org/bugzilla/show_bug.cgi?id=9697
118 | Bug-Debian: http://bugs.debian.org/510219
119 |
120 | A patch created by the Debian maintainer John Doe, which got forwarded and rejected:
121 |
122 | .. code-block:: none
123 |
124 | Description: Use FHS compliant paths by default
125 | Upstream is not interested in switching to those paths.
126 | .
127 | But we will continue using them in Debian nevertheless to comply with
128 | our policy.
129 | Forwarded: http://lists.example.com/oct-2006/1234.html
130 | Author: John Doe
131 | Last-Update: 2006-12-21
132 |
133 | A vendor specific patch not meant for upstream submitted on the BTS by a Debian developer:
134 |
135 | .. code-block:: none
136 |
137 | Description: Workaround for broken symbol resolving on mips/mipsel
138 | The correct fix will be done in etch and it will require toolchain
139 | fixes.
140 | Forwarded: not-needed
141 | Origin: vendor, http://bugs.debian.org/cgi-bin/bugreport.cgi?msg=80;bug=265678
142 | Bug-Debian: http://bugs.debian.org/265678
143 | Author: Thiemo Seufer
144 |
145 | A patch submitted and applied upstream:
146 |
147 | .. code-block:: none
148 |
149 | Description: Fix widget frobnication speeds
150 | Frobnicating widgets too quickly tended to cause explosions.
151 | Forwarded: http://lists.example.com/2010/03/1234.html
152 | Author: John Doe
153 | Applied-Upstream: 1.2, http://bzr.example.com/frobnicator/trunk/revision/123
154 | Last-Update: 2010-03-29
155 |
156 | Resources
157 | ---------
158 |
159 | - `DEP-3 Specification -- Patch Tagging Guidelines `_
160 |
161 | .. |required| replace:: :bdg-primary:`required`
162 | .. |optional| replace:: :bdg-secondary:`optional`
163 |
--------------------------------------------------------------------------------
/docs/how-to/get-package-source.rst:
--------------------------------------------------------------------------------
1 | .. _get-package-source:
2 |
3 | Get the source of a package
4 | ===========================
5 |
6 | Before you can work on a :term:`source package` you need to get
7 | the :term:`source code` of that package. This article presents
8 | four ways to achieve this: :command:`git-ubuntu`, :command:`pull-pkg`, and
9 | :command:`apt-get source`, and :command:`dget`.
10 |
11 | git-ubuntu
12 | ----------
13 |
14 | .. note::
15 |
16 | ``git-ubuntu`` is the modern way of working with :term:`Ubuntu`
17 | source packages.
18 |
19 | .. warning::
20 |
21 | ``git-ubuntu`` is still in active development and these instructions
22 | will likely change over time. While ``git-ubuntu`` will become the
23 | default packaging method, for now you may encounter rough edges or
24 | unsupported edge cases. You can ask for help in the ``#ubuntu-devel``
25 | channel or `open a bug report `_ on :term:`Launchpad`.
26 | Bug reports are very welcome!
27 |
28 | Install
29 | ~~~~~~~
30 |
31 | The following command will install ``git-ubuntu``:
32 |
33 | .. code-block:: bash
34 |
35 | sudo snap install --classic --edge git-ubuntu
36 |
37 | Basic usage
38 | ~~~~~~~~~~~
39 |
40 | To clone a source package git repository to a directory:
41 |
42 | .. code-block:: bash
43 |
44 | git-ubuntu clone PACKAGE [DIRECTORY]
45 |
46 |
47 | To generate the :term:`orig tarballs ` for a given source package:
48 |
49 | .. code-block:: bash
50 |
51 | git-ubuntu export-orig
52 |
53 | Example
54 | ~~~~~~~
55 |
56 | .. code-block:: bash
57 |
58 | git-ubuntu clone hello
59 | cd hello
60 | git-ubuntu export-orig
61 |
62 | You can find further information in these two blog articles (note that they are from 2017):
63 |
64 | - `git-ubuntu clone `_
65 | - `Git Ubuntu: More on the imported repositories `_
66 |
67 | pull-pkg
68 | --------
69 |
70 | The :command:`pull-pkg` command is part of the ``ubuntu-dev-tools`` package
71 | and downloads a specific version of a source package, or the latest version
72 | from a specified release.
73 |
74 | Install
75 | ~~~~~~~
76 |
77 | The following command will install ``ubtuntu-dev-tools``, which includes
78 | :command:`pull-pkg`:
79 |
80 | .. code-block:: bash
81 |
82 | sudo apt update && sudo apt install ubuntu-dev-tools
83 |
84 | Basic usage
85 | ~~~~~~~~~~~
86 |
87 | .. code-block:: none
88 |
89 | pull-pkg [OPTIONS] PACKAGE-NAME [SERIES|VERSION]
90 |
91 | You can find further information on the manual page :manpage:`pull-pkg(1)`.
92 |
93 | Examples
94 | ~~~~~~~~
95 |
96 | There are convenience scripts that follow a similar syntax and set the
97 | ``OPTIONS`` for pull type and :term:`Distribution` appropriately. Here are
98 | three examples (although there are others):
99 |
100 | :command:`pull-lp-source`
101 | ^^^^^^^^^^^^^^^^^^^^^^^^^
102 |
103 | * To download the latest version of the ``hello`` source package for the
104 | :term:`Current Release in Development` from Launchpad:
105 |
106 | .. code-block:: bash
107 |
108 | pull-lp-source hello
109 |
110 | * To download the latest version of the ``hello`` source package for the
111 | Ubuntu ``mantic`` release from Launchpad:
112 |
113 | .. code-block:: bash
114 |
115 | pull-lp-source hello mantic
116 |
117 | * To download version ``2.10-3`` of the ``hello`` source package from Launchpad:
118 |
119 | .. code-block:: bash
120 |
121 | pull-lp-source hello 2.10-3
122 |
123 | :command:`pull-ppa-source`
124 | ^^^^^^^^^^^^^^^^^^^^^^^^^^
125 |
126 | * To download the latest version of the ``hello`` source package from the
127 | Launchpad :term:`Personal Package Archive` (PPA), also called ``hello``, of
128 | the user ``dviererbe``:
129 |
130 | .. code-block:: bash
131 |
132 | pull-ppa-source --ppa 'dviererbe/hello' 'hello'
133 |
134 | * To download the latest version of the ``hello`` source package for the
135 | ``mantic`` release from the same Launchpad PPA:
136 |
137 | .. code-block:: bash
138 |
139 | pull-ppa-source --ppa 'dviererbe/hello' 'hello' 'mantic'
140 |
141 | * To download version ``2.10-3`` of the ``hello`` source package for the
142 | ``mantic`` release from the same Launchpad PPA:
143 |
144 | .. code-block:: bash
145 |
146 | pull-ppa-source --ppa 'dviererbe/hello' 'hello' '2.10-3'
147 |
148 | :command:`pull-debian-source`
149 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
150 |
151 | * To download the latest version of the ``hello`` source package from
152 | :term:`Debian`:
153 |
154 | .. code-block:: bash
155 |
156 | pull-debian-source 'hello'
157 |
158 | * To download the latest version of the ``hello`` source package for the
159 | ``sid`` release from Debian:
160 |
161 | .. code-block:: bash
162 |
163 | pull-debian-source 'hello' 'sid'
164 |
165 | * To download the version ``2.10-3`` of the ``hello`` source package from Debian:
166 |
167 | .. code-block:: bash
168 |
169 | pull-debian-source 'hello' '2.10-3'
170 |
171 | :command:`apt-get source`
172 | -------------------------
173 |
174 | The :term:`APT` package manager can also fetch source packages.
175 |
176 | .. important::
177 |
178 | Source packages are tracked separately from
179 | :term:`binary packages ` via ``deb-src`` lines in the
180 | :manpage:`sources.list(5)` files. This means that you will need to add
181 | such a line for each :term:`repository ` you want to get source
182 | packages from; otherwise you will probably get either the wrong (too old/too new)
183 | source package versions -- or none at all.
184 |
185 | Basic usage
186 | ~~~~~~~~~~~
187 |
188 | .. tabs::
189 |
190 | .. group-tab:: apt
191 |
192 | .. code-block:: none
193 |
194 | apt source PACKAGE-NAME
195 |
196 | You can find further information on the manual page :manpage:`apt(8)`.
197 |
198 | .. group-tab:: apt-get
199 |
200 | .. code-block:: none
201 |
202 | apt-get source PACKAGE-NAME
203 |
204 | You can find further information on the manual page :manpage:`apt-get(8)`.
205 |
206 | Example
207 | ~~~~~~~
208 |
209 | .. tabs::
210 |
211 | .. code-tab:: bash apt
212 |
213 | apt source 'hello'
214 |
215 | .. code-tab:: bash apt-get
216 |
217 | apt-get source 'hello'
218 |
219 | ``dget``
220 | --------
221 |
222 | The :command:`dget` command is part of the ``devscripts`` package. If you call
223 | it with the URL of a ``.dsc`` or ``.changes`` file it acts as a source package
224 | aware :manpage:`wget(1)` and downloads all associated files that are listed in
225 | the ``.dsc`` or ``.changes`` file (debian tarball, :term:`orig tarballs `,
226 | :term:`upstream` :term:`signatures `).
227 |
228 | Install
229 | ~~~~~~~
230 |
231 | .. code-block:: bash
232 |
233 | sudo apt update && sudo apt install devscripts
234 |
235 | Basic usage
236 | ~~~~~~~~~~~
237 |
238 | .. code-block:: bash
239 |
240 | dget URL
241 |
242 | Example
243 | ~~~~~~~
244 |
245 | Go to Launchpad and select the package you want to download (in this example;
246 | the latest version of the ``hello`` source package):
247 |
248 | .. image:: ../images/how-to/get-package-source/lp-hello-package.png
249 | :align: center
250 | :width: 35 em
251 | :alt: Launchpad overview page for the hello source package with an arrow pointing to the Mantic Minotaur 2.10-3 release.
252 |
253 | Next, copy the download link of the ``.dsc`` file:
254 |
255 | .. image:: ../images/how-to/get-package-source/lp-hello-package-2.10-3.png
256 | :align: center
257 | :width: 35 em
258 | :alt: Launchpad overview page for the 2.10-3 release of the hello source package with an arrow pointing to the .dsc file link.
259 |
260 | Finally, call ``dget`` with the copied URL:
261 | .. code-block:: bash
262 |
263 | dget https://launchpad.net/ubuntu/+archive/primary/+sourcefiles/hello/2.10-3/hello_2.10-3.dsc
264 |
265 | Note that this works for links from Debian and Launchpad Personal Package Archives too.
266 |
267 | You can find further information on the manual page :manpage:`dget(1)`.
268 |
--------------------------------------------------------------------------------
/docs/explanation/releases.rst:
--------------------------------------------------------------------------------
1 | .. _UbuntuReleases:
2 |
3 | Ubuntu releases
4 | ===============
5 |
6 | Release cadence
7 | ---------------
8 |
9 | :term:`Ubuntu` follows a strict time-based release cycle. Every six months since
10 | 2004, :term:`Canonical` publishes a new Ubuntu version and its set of
11 | :term:`packages ` are declared stable (production-quality). Simultaneously,
12 | a new version begins development; it is given its own :term:`Code name`, but also referred
13 | to as the ":term:`Current Release in Development`" or ":term:`Devel`".
14 |
15 | .. _LTSReleases:
16 |
17 | LTS releases
18 | ~~~~~~~~~~~~
19 |
20 | Since 2006, every fourth release, made every two years in April, receives
21 | :ref:`LongTermSupport` for large-scale deployments. This is the origin of the
22 | term "LTS" for stable, maintained releases.
23 |
24 | An estimated 95% of all Ubuntu installations are LTS releases.
25 |
26 | .. note::
27 |
28 | Because of the strict time-based six months release cycle, you will only
29 | see LTS releases in even-numbered years (e.g. ``18``, ``20``, ``22``) in
30 | April (``04``). The only exception to this rule was Ubuntu 6.06 LTS (Dapper
31 | Drake).
32 |
33 | .. _PointReleases:
34 |
35 | Point releases
36 | ~~~~~~~~~~~~~~
37 |
38 | To ensure that a fresh install of an :ref:`LTS release ` will work
39 | on newer hardware and not require a big download of additional updates,
40 | Canonical publishes **point releases** that include all the updates made so far.
41 |
42 | The first point release of an LTS is published three months after the initial
43 | release and repeated every six months at least until the next LTS is published.
44 | In practice, Canonical may publish even more point releases for an LTS series,
45 | depending on the popularity of that LTS series.
46 |
47 | For example, the Ubuntu 16.04.7 LTS (Xenial Xerus) point release was published
48 | more than four years after the initial release of Ubuntu 16.04 LTS.
49 |
50 | .. _InterimReleases:
51 |
52 | Interim releases
53 | ~~~~~~~~~~~~~~~~
54 |
55 | In the years between LTS releases, Canonical also produces **interim releases**,
56 | sometimes also called "regular releases".
57 |
58 | Many developers use interim releases because they provide newer compilers or
59 | access to newer :term:`Kernels ` and newer libraries, and they are often
60 | used inside rapid DevOps processes like :term:`CI`/:term:`CD` pipelines where
61 | the lifespan of an artefact is likely to be shorter than the support period of
62 | the interim release.
63 |
64 | Why does Ubuntu use time-based releases?
65 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
66 |
67 | Ubuntu releases represent an aggregation of the work of thousands of independent
68 | software projects. The time-based release process provides users with the best
69 | balance of the latest software, tight integration, and excellent overall quality.
70 |
71 | Ubuntu version format
72 | ---------------------
73 |
74 | .. code:: text
75 |
76 | YY.MM[.POINT-RELEASE] [LTS]
77 |
78 | Ubuntu version identifier as used for Ubuntu releases consist of
79 | four components, which are:
80 |
81 | ``YY``
82 | The 2-digit year number of the initial release.
83 |
84 | ``MM``
85 | The 2-digit month number of the initial release.
86 |
87 | .. note::
88 |
89 | Because of the strict time-based six months release cycle, you will
90 | usually only see releases in April (``04``) and October (``10``).
91 |
92 | ``POINT-RELEASE``
93 | The :ref:`point release ` number starts at ``1`` and
94 | increments with every additional point release.
95 |
96 | This component is omitted for the initial release, in which case zero is
97 | assumed.
98 |
99 | ``LTS``
100 | Any Ubuntu release that receives long term support will be marked with
101 | ``LTS`` (see the :ref:`release lifespan ` section for
102 | more information).
103 |
104 | Any Ubuntu release that does not receive long term support omits this component.
105 |
106 | Examples
107 | ~~~~~~~~
108 |
109 | .. list-table::
110 | :header-rows: 1
111 |
112 | * - Version Identifier
113 | - Release Date
114 | - Support
115 | - End of Standard Support
116 | - End of Life
117 | * - ``22.04 LTS``
118 | - 21 April 2022
119 | - Long term
120 | - April 2027
121 | - April 2032
122 | * - ``22.04.1 LTS``
123 | - 11 August 2022
124 | - Long term
125 | - April 2027
126 | - April 2032
127 | * - ``22.10``
128 | - 22 October 2022
129 | - Regular
130 | - July 2023
131 | - July 2023
132 | * - ``22.04.2 LTS``
133 | - 13 February 2023
134 | - Long term
135 | - April 2027
136 | - April 2032
137 | * - ``23.04``
138 | - 20 April 2022
139 | - Regular
140 | - January 2024
141 | - January 2024
142 |
143 | .. _UbuntuReleaseLifespan:
144 |
145 | Release lifespan
146 | ----------------
147 |
148 | Every Ubuntu :term:`Series` receives the same production-grade support quality,
149 | but the length of time for which an Ubuntu series receives support varies.
150 |
151 | .. _RegularSupport:
152 |
153 | Regular support
154 | ~~~~~~~~~~~~~~~
155 |
156 | :ref:`InterimReleases` are production-quality releases and are supported for
157 | nine months, with sufficient time provided for users to update, but these
158 | releases do not receive the long-term commitment of LTS releases.
159 |
160 | .. _LongTermSupport:
161 |
162 | Long Term Support (LTS)
163 | ~~~~~~~~~~~~~~~~~~~~~~~
164 |
165 | LTS releases receive five years of standard security maintenance for all
166 | packages in the :term:`Main` :term:`Component`. With an :term:`Ubuntu Pro`
167 | subscription, you get access to :term:`Expanded Security Maintenance`
168 | (:term:`ESM`), covering security fixes for packages in the :term:`Universe`
169 | :term:`Component`. ESM also extends the lifetime of an LTS series from five
170 | years to ten years.
171 |
172 | Editions
173 | --------
174 |
175 | Every Ubuntu release is provided as both a :term:`Server ` and
176 | :term:`Desktop ` edition.
177 |
178 | Ubuntu Desktop provides a graphical :term:`User Interface` (:term:`GUI`) for
179 | everyday computing tasks, making it suitable for personal computers and laptops.
180 | :term:`Ubuntu Server`, on the other hand, provides a text-based :term:`User Interface`
181 | (:term:`TUI`) instead of a :term:`GUI`, optimised for server environments, that
182 | allows machines on the server to be run headless, focusing on server-related
183 | services and applications, making it ideal for hosting web services, databases, and
184 | other server functions.
185 |
186 | Additionally, each release of Ubuntu is available in minimal configurations,
187 | which have the fewest possible packages installed: available in the
188 | installer for Ubuntu Server, Ubuntu Desktop, and as separate cloud images.
189 |
190 | Canonical publishes Ubuntu on all major public clouds, and the latest :term:`image`
191 | for each LTS version will always include any security update provided since the
192 | LTS release date, until two weeks prior to the image creation date.
193 |
194 | Ubuntu flavours
195 | ---------------
196 |
197 | Ubuntu flavours are :term:`Distributions ` of the default Ubuntu
198 | releases, which choose their own default applications and settings. Ubuntu
199 | flavours are owned and developed by members of the Ubuntu community and backed
200 | by the full :term:`Ubuntu Archive` for packages and updates.
201 |
202 | Officially recognised flavours are:
203 |
204 | - `Edubuntu`_
205 | - `Kubuntu`_
206 | - `Lubuntu`_
207 | - `Ubuntu Budgie`_
208 | - `Ubuntu Cinnamon`_
209 | - `Ubuntu Kylin`_
210 | - `Ubuntu MATE`_
211 | - `Ubuntu Studio`_
212 | - `Ubuntu Unity`_
213 | - `Xubuntu`_
214 |
215 | In addition to the officially recognised flavours, dozens of other :term:`Linux`
216 | distributions take Ubuntu as a base for their own distinctive ideas and approaches.
217 |
218 | Resources
219 | ---------
220 |
221 | - `The Ubuntu life cycle and release cadence `_
222 | - `Ubuntu wiki -- List of releases `_
223 | - `Ubuntu flavours `_
224 | - `Ubuntu wiki -- Ubuntu flavours `_
225 | - `Ubuntu wiki -- time-based releases `_
226 | - `Ubuntu wiki -- point release process `_
227 | - `Ubuntu wiki -- end of life process `_
228 | - `Ubuntu releases `_
229 | - `Ask a bug supervisor `
230 | - `contact the Ubuntu SRU Team `
231 |
--------------------------------------------------------------------------------
/docs/how-to/patch-management.rst:
--------------------------------------------------------------------------------
1 | Patch management
2 | ================
3 |
4 | This article demonstrates how to manage the :term:`patches ` of a
5 | :term:`source package ` in the ``3.0 (quilt)`` format.
6 |
7 | See the :doc:`patches explanation article ` for more
8 | background information about patches in the context of :term:`Ubuntu`.
9 |
10 | .. note::
11 |
12 | If the format is ``3.0 (native)``, this article is not of interest for you and
13 | simply write your changes to the files. There is no need to explicitly create
14 | and track a patch for native packages.
15 | See the :doc:`package model ` article for more
16 | information about package formats.
17 |
18 | As the source package format implies, we will use the :manpage:`quilt(1)` tool
19 | to manage the patches of a source package. Quilt manages patches like a
20 | :term:`Stack`. It maintains a list of patches (also called "series")
21 | that get applied one after another from top to bottom in the order
22 | they are listed in :file:`debian/patches/series`, excluding lines starting with ``#``.
23 |
24 | .. important::
25 |
26 | Quilt will create a ``.pc/`` directory at the source package root
27 | directory. This is the location where Quilt will store control files
28 | similar to the ``.git/`` folder of a :term:`Git` repository.
29 |
30 | Before you commit any changes (e.g., with :term:`git-ubuntu`) or attempt
31 | to build the source package, **do not forget to unapply all patches and
32 | delete the directory:**
33 |
34 | .. code-block:: none
35 |
36 | quilt pop -a && rm -r .pc
37 |
38 | You can avoid removing ``.pc`` if it exists in the
39 | ``.gitignore`` file, or if you can otherwise avoid it when running
40 | ``git add``.
41 |
42 | Prerequisites
43 | -------------
44 |
45 | If you haven't already, install :manpage:`quilt(1)`:
46 |
47 | .. include:: /reuse/snippets/quilt/setup.rst
48 |
49 | List patches
50 | ------------
51 |
52 | List all available patches:
53 |
54 | .. code-block:: none
55 |
56 | quilt series
57 |
58 | This will also color code which patches are applied (green), which patch is the
59 | latest applied patch (yellow) and which patches are unapplied (white).
60 |
61 | List applied patches:
62 |
63 | .. code-block:: none
64 |
65 | quilt applied
66 |
67 | Display the topmost applied patch:
68 |
69 | .. code-block:: none
70 |
71 | quilt top
72 |
73 | List unapplied patches:
74 |
75 | .. code-block:: none
76 |
77 | quilt unapplied
78 |
79 | .. note::
80 |
81 | Quilt patches are applied from top to bottom in the order they are listed.
82 |
83 | .. _ApplyPatches:
84 |
85 | Apply patches
86 | -------------
87 |
88 | Apply the next patch:
89 |
90 | .. code-block:: none
91 |
92 | quilt push
93 |
94 | Apply all patches:
95 |
96 | .. code-block:: none
97 |
98 | quilt push -a
99 |
100 | Apply the next ``N`` patches
101 |
102 | .. code-block:: none
103 |
104 | quilt push N
105 |
106 | Apply all patches until (including) a specific patch:
107 |
108 | .. code-block:: none
109 |
110 | quilt push PATCH-NAME
111 |
112 | This can also be the path of the patch (allowing for auto-completion):
113 |
114 | .. code-block:: none
115 |
116 | quilt push debian/series/PATCH-NAME
117 |
118 | Unapply patches
119 | ---------------
120 |
121 | This works similar to applying patches.
122 |
123 | Unapply the patch on top:
124 |
125 | .. code-block:: none
126 |
127 | quilt pop
128 |
129 | Unapply all patches:
130 |
131 | .. code-block:: none
132 |
133 | quilt pop -a
134 |
135 | Unapply the ``N`` topmost applied patches
136 |
137 | .. code-block:: none
138 |
139 | quilt pop N
140 |
141 | Unapply all patches until (excluding) a specific patch:
142 |
143 | .. code-block:: none
144 |
145 | quilt pop PATCH-NAME
146 |
147 | This can also be the path of the patch (allowing for auto-completion):
148 |
149 | .. code-block:: none
150 |
151 | quilt pop debian/series/PATCH-NAME
152 |
153 | .. _VerifyPatches:
154 |
155 | Verify patches
156 | --------------
157 |
158 | Now that we know how to apply and unapply patches we can verify if all patches
159 | apply and unapply cleanly. This can be useful when you merge changes from
160 | Debian into an Ubuntu package and want to check if everything is still in
161 | order.
162 |
163 | 1. We verify that all patches apply cleanly:
164 |
165 | .. code-block:: none
166 |
167 | quilt push -a
168 |
169 | 2. We verify that all patches unapply cleanly:
170 |
171 | .. code-block:: none
172 |
173 | quilt pop -a
174 |
175 | 3. (optional) We remove the Quilt control file folder:
176 |
177 | .. code-block:: none
178 |
179 | rm -r .pc
180 |
181 | Show details about a patch file
182 | -------------------------------
183 |
184 | Print the header of the topmost applied or specified patch:
185 |
186 | .. code-block:: none
187 |
188 | quilt header [PATCH-NAME]
189 |
190 | Print the list of files that the topmost applied or specified patch changes:
191 |
192 | .. code-block:: none
193 |
194 | quilt files [PATCH-NAME]
195 |
196 | Print the changes by the topmost applied or specified patch to the specified file(s)
197 | in a diff format. If no files are specified, all files that are changes are included.
198 |
199 | .. code-block:: none
200 |
201 | quilt diff [-P PATCH-NAME] [FILE-PATH ...]
202 |
203 |
204 | Rename a patch file
205 | -------------------
206 |
207 | Rename the topmost applied or specified patch:
208 |
209 | .. code-block:: none
210 |
211 | quilt rename [-P PATCH-NAME] NEW-PATCH-NAME
212 |
213 | Remove a patch file
214 | -------------------
215 |
216 | Remove the topmost applied or specified patch from the :file:`debian/patches/series` file.
217 | Use ``-r`` to also delete the patch file from the :file:`debian/patches` directory:
218 |
219 | .. code-block:: none
220 |
221 | quilt delete [-r] [PATCH-NAME]
222 |
223 | Generate a patch file
224 | ---------------------
225 |
226 | 1. Create a new patch after the topmost applied patch:
227 |
228 | .. code-block:: none
229 |
230 | quilt new PATCH-NAME
231 |
232 | .. note::
233 |
234 | It is best practice to read the existing patch-file-names in :file:`debian/patches`
235 | and ensure your new patch name is consistent with the existing ones.
236 |
237 | 2. Edit files outside the :file:`debian/` directory by following the same steps as
238 | outlined by the following section :ref:`EditPatches`.
239 |
240 | .. _EditPatches:
241 |
242 | Edit a patch file
243 | -----------------
244 |
245 | 1. Apply all patches until the patch we want to edit:
246 |
247 | .. code-block:: none
248 |
249 | quilt push PATCH-NAME
250 |
251 | 2. There are multiple approaches how to edit the patch file:
252 |
253 | - Edit the patch header:
254 |
255 | .. code-block:: none
256 |
257 | quilt header -e
258 |
259 | .. tip::
260 |
261 | If the patch does not already have a header and you want to add one; add the
262 | ``--dep3`` flag to insert a :term:`DEP 3` patch header template:
263 |
264 | .. code-block:: none
265 |
266 | quilt header --dep3 -e
267 |
268 | .. tip::
269 |
270 | See the :doc:`DEP 3 -- Patch file headers reference `
271 | which lists and briefly explains standard DEP 3 compliant fields and shows sample
272 | DEP 3 compliant headers.
273 |
274 | - Edit specific file(s) with a text editor after adding the changes to the patch file:
275 |
276 | .. code-block:: none
277 |
278 | quilt edit FILE-PATH ...
279 |
280 | .. note::
281 |
282 | Opens the files in ``$EDITOR`` -- this is usually your default terminal editor.
283 |
284 | - Edit specific file(s) manually (without immediately opening an editor):
285 |
286 | a. Check which files are already changed by the patch file:
287 |
288 | .. code-block:: none
289 |
290 | quilt files
291 |
292 | b. If you want to edit file(s) that the patch currently does NOT change
293 | -- add these files to the patch before editing them:
294 |
295 | .. code-block:: none
296 |
297 | quilt add FILE-PATH ...
298 |
299 | .. note::
300 |
301 | You can directly edit files which are already changed by the patch.
302 |
303 | .. tip::
304 |
305 | To see the changes of the patch file to a specific file:
306 |
307 | .. code-block:: none
308 |
309 | quilt diff FILE-PATH
310 |
311 | To see the changes you made of the patch file:
312 |
313 | .. code-block:: none
314 |
315 | quilt diff -z
316 |
317 | c. Save the changes to the patch file:
318 |
319 | .. code-block:: none
320 |
321 | quilt refresh
322 |
323 | - Delete the changes of a patch to specific file(s):
324 |
325 | .. code-block:: none
326 |
327 | quilt remove FILE-PATH ...
328 |
329 | 3. (recommended) If there are patches after the patch you have edited --
330 | :ref:`verify that all patches still apply cleanly `.
331 |
332 |
333 | Import a patch file
334 | -------------------
335 |
336 | Insert patch files following the current topmost applied patch:
337 |
338 | .. code-block:: none
339 |
340 | quilt import PATCH-FILE-PATH ...
341 |
342 | .. important::
343 |
344 | The patch files have to be outside the :file:`debian/patches/` directory.
345 |
346 | .. note::
347 |
348 | The imported patches do not get applied automatically. You must
349 | :ref:`apply the patches ` after importing them.
350 |
351 |
352 | Resources
353 | ---------
354 |
355 | - :doc:`DEP 3 -- Patch file headers (reference) `
356 | - :doc:`Patches (explanation) `
357 | - manual page :manpage:`quilt(1)`
358 | - `Debian wiki -- Using quilt in Debian source packages `_
359 |
--------------------------------------------------------------------------------
/docs/.sphinx/_static/custom.css:
--------------------------------------------------------------------------------
1 | /**
2 | Ubuntu variable font definitions.
3 | Based on https://github.com/canonical/vanilla-framework/blob/main/scss/_base_fontfaces.scss
4 |
5 | When font files are updated in Vanilla, the links to font files will need to be updated here as well.
6 | */
7 |
8 | /* default font set */
9 | @font-face {
10 | font-family: 'Ubuntu variable';
11 | font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */
12 | font-style: normal;
13 | font-weight: 100 800; /* min and max value for the weight axis */
14 | src: url('https://assets.ubuntu.com/v1/f1ea362b-Ubuntu%5Bwdth,wght%5D-latin-v0.896a.woff2') format('woff2-variations');
15 | }
16 |
17 | @font-face {
18 | font-family: 'Ubuntu variable';
19 | font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */
20 | font-style: italic;
21 | font-weight: 100 800; /* min and max value for the weight axis */
22 | src: url('https://assets.ubuntu.com/v1/90b59210-Ubuntu-Italic%5Bwdth,wght%5D-latin-v0.896a.woff2') format('woff2-variations');
23 | }
24 |
25 | @font-face {
26 | font-family: 'Ubuntu Mono variable';
27 | font-style: normal;
28 | font-weight: 100 800; /* min and max value for the weight axis */
29 | src: url('https://assets.ubuntu.com/v1/d5fc1819-UbuntuMono%5Bwght%5D-latin-v0.869.woff2') format('woff2-variations');
30 | }
31 |
32 | /* cyrillic-ext */
33 | @font-face {
34 | font-family: 'Ubuntu variable';
35 | font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */
36 | font-style: normal;
37 | font-weight: 100 800; /* min and max value for the weight axis */
38 | src: url('https://assets.ubuntu.com/v1/77cd6650-Ubuntu%5Bwdth,wght%5D-cyrillic-extended-v0.896a.woff2') format('woff2-variations');
39 | unicode-range: U+0460-052F, U+20B4, U+2DE0-2DFF, U+A640-A69F;
40 | }
41 |
42 | /* cyrillic */
43 | @font-face {
44 | font-family: 'Ubuntu variable';
45 | font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */
46 | font-style: normal;
47 | font-weight: 100 800; /* min and max value for the weight axis */
48 | src: url('https://assets.ubuntu.com/v1/2702fce5-Ubuntu%5Bwdth,wght%5D-cyrillic-v0.896a.woff2') format('woff2-variations');
49 | unicode-range: U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;
50 | }
51 |
52 | /* greek-ext */
53 | @font-face {
54 | font-family: 'Ubuntu variable';
55 | font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */
56 | font-style: normal;
57 | font-weight: 100 800; /* min and max value for the weight axis */
58 | src: url('https://assets.ubuntu.com/v1/5c108b7d-Ubuntu%5Bwdth,wght%5D-greek-extended-v0.896a.woff2') format('woff2-variations');
59 | unicode-range: U+1F00-1FFF;
60 | }
61 |
62 | /* greek */
63 | @font-face {
64 | font-family: 'Ubuntu variable';
65 | font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */
66 | font-style: normal;
67 | font-weight: 100 800; /* min and max value for the weight axis */
68 | src: url('https://assets.ubuntu.com/v1/0a14c405-Ubuntu%5Bwdth,wght%5D-greek-v0.896a.woff2') format('woff2-variations');
69 | unicode-range: U+0370-03FF;
70 | }
71 |
72 | /* latin-ext */
73 | @font-face {
74 | font-family: 'Ubuntu variable';
75 | font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */
76 | font-style: normal;
77 | font-weight: 100 800; /* min and max value for the weight axis */
78 | src: url('https://assets.ubuntu.com/v1/19f68eeb-Ubuntu%5Bwdth,wght%5D-latin-extended-v0.896a.woff2') format('woff2-variations');
79 | unicode-range: U+0100-024F, U+1E00-1EFF, U+20A0-20AB, U+20AD-20CF, U+2C60-2C7F, U+A720-A7FF;
80 | }
81 |
82 |
83 | /** Define font-weights as per Vanilla
84 | Based on: https://github.com/canonical/vanilla-framework/blob/main/scss/_base_typography-definitions.scss
85 |
86 | regular text: 400,
87 | bold: 550,
88 | thin: 300,
89 |
90 | h1: bold,
91 | h2: 180;
92 | h3: bold,
93 | h4: 275,
94 | h5: bold,
95 | h6: regular
96 | */
97 |
98 | /* default regular text */
99 | html {
100 | font-weight: 400;
101 | }
102 |
103 | /* heading specific definitions */
104 | h1, h3, h5 { font-weight: 550; }
105 | h2 { font-weight: 180; }
106 | h4 { font-weight: 275; }
107 |
108 | /* bold */
109 | .toc-tree li.scroll-current>.reference,
110 | dl.glossary dt,
111 | dl.simple dt,
112 | dl:not([class]) dt {
113 | font-weight: 550;
114 | }
115 |
116 |
117 | /** Table styling **/
118 |
119 | th.head {
120 | text-transform: uppercase;
121 | font-size: var(--font-size--small);
122 | text-align: initial;
123 | }
124 |
125 | table.align-center th.head {
126 | text-align: center
127 | }
128 |
129 | table.docutils {
130 | border: 0;
131 | box-shadow: none;
132 | width:100%;
133 | }
134 |
135 | table.docutils td, table.docutils th, table.docutils td:last-child, table.docutils th:last-child, table.docutils td:first-child, table.docutils th:first-child {
136 | border-right: none;
137 | border-left: none;
138 | }
139 |
140 | /* Allow to centre text horizontally in table data cells */
141 | table.align-center {
142 | text-align: center !important;
143 | }
144 |
145 | /** No rounded corners **/
146 |
147 | .admonition, code.literal, .sphinx-tabs-tab, .sphinx-tabs-panel, .highlight {
148 | border-radius: 0;
149 | }
150 |
151 | /** Admonition styling **/
152 |
153 | .admonition {
154 | border-top: 1px solid #d9d9d9;
155 | border-right: 1px solid #d9d9d9;
156 | border-bottom: 1px solid #d9d9d9;
157 | }
158 |
159 | /** Color for the "copy link" symbol next to headings **/
160 |
161 | a.headerlink {
162 | color: var(--color-brand-primary);
163 | }
164 |
165 | /** Line to the left of the current navigation entry **/
166 |
167 | .sidebar-tree li.current-page {
168 | border-left: 2px solid var(--color-brand-primary);
169 | }
170 |
171 | /** Some tweaks for issue #16 **/
172 |
173 | [role="tablist"] {
174 | border-bottom: 1px solid var(--color-sidebar-item-background--hover);
175 | }
176 |
177 | .sphinx-tabs-tab[aria-selected="true"] {
178 | border: 0;
179 | border-bottom: 2px solid var(--color-brand-primary);
180 | background-color: var(--color-sidebar-item-background--current);
181 | font-weight:300;
182 | }
183 |
184 | .sphinx-tabs-tab{
185 | color: var(--color-brand-primary);
186 | font-weight:300;
187 | }
188 |
189 | .sphinx-tabs-panel {
190 | border: 0;
191 | border-bottom: 1px solid var(--color-sidebar-item-background--hover);
192 | background: var(--color-background-primary);
193 | }
194 |
195 | button.sphinx-tabs-tab:hover {
196 | background-color: var(--color-sidebar-item-background--hover);
197 | }
198 |
199 | /** Custom classes to fix scrolling in tables by decreasing the
200 | font size or breaking certain columns.
201 | Specify the classes in the Markdown file with, for example:
202 | ```{rst-class} break-col-4 min-width-4-8
203 | ```
204 | **/
205 |
206 | table.dec-font-size {
207 | font-size: smaller;
208 | }
209 | table.break-col-1 td.text-left:first-child {
210 | word-break: break-word;
211 | }
212 | table.break-col-4 td.text-left:nth-child(4) {
213 | word-break: break-word;
214 | }
215 | table.min-width-1-15 td.text-left:first-child {
216 | min-width: 15em;
217 | }
218 | table.min-width-4-8 td.text-left:nth-child(4) {
219 | min-width: 8em;
220 | }
221 |
222 | /** Underline for abbreviations **/
223 |
224 | abbr[title] {
225 | text-decoration: underline solid #cdcdcd;
226 | }
227 |
228 | /** Use the same style for right-details as for left-details **/
229 | .bottom-of-page .right-details {
230 | font-size: var(--font-size--small);
231 | display: block;
232 | }
233 |
234 | /** Version switcher */
235 | button.version_select {
236 | color: var(--color-foreground-primary);
237 | background-color: var(--color-toc-background);
238 | padding: 5px 10px;
239 | border: none;
240 | }
241 |
242 | .version_select:hover, .version_select:focus {
243 | background-color: var(--color-sidebar-item-background--hover);
244 | }
245 |
246 | .version_dropdown {
247 | position: relative;
248 | display: inline-block;
249 | text-align: right;
250 | font-size: var(--sidebar-item-font-size);
251 | }
252 |
253 | .available_versions {
254 | display: none;
255 | position: absolute;
256 | right: 0px;
257 | background-color: var(--color-toc-background);
258 | box-shadow: 0px 8px 16px 0px rgba(0,0,0,0.2);
259 | z-index: 11;
260 | }
261 |
262 | .available_versions a {
263 | color: var(--color-foreground-primary);
264 | padding: 12px 16px;
265 | text-decoration: none;
266 | display: block;
267 | }
268 |
269 | .available_versions a:hover {background-color: var(--color-sidebar-item-background--current)}
270 |
271 | .show {display:block;}
272 |
273 | /** Fix for nested numbered list - the nested list is lettered **/
274 | ol.arabic ol.arabic {
275 | list-style: lower-alpha;
276 | }
277 |
278 | /** Make expandable sections look like links **/
279 | details summary {
280 | color: var(--color-link);
281 | }
282 |
283 | /** Fix the styling of the version box for readthedocs **/
284 |
285 | #furo-readthedocs-versions .rst-versions, #furo-readthedocs-versions .rst-current-version, #furo-readthedocs-versions:focus-within .rst-current-version, #furo-readthedocs-versions:hover .rst-current-version {
286 | background: var(--color-sidebar-item-background--hover);
287 | }
288 |
289 | .rst-versions .rst-other-versions dd a {
290 | color: var(--color-link);
291 | }
292 |
293 | #furo-readthedocs-versions:focus-within .rst-current-version .fa-book, #furo-readthedocs-versions:hover .rst-current-version .fa-book, .rst-versions .rst-other-versions {
294 | color: var(--color-sidebar-link-text);
295 | }
296 |
297 | .rst-versions .rst-current-version {
298 | color: var(--color-version-popup);
299 | font-weight: bolder;
300 | }
301 |
302 | /* Code-block copybutton invisible by default
303 | (overriding Furo config to achieve default copybutton setting). */
304 | .highlight button.copybtn {
305 | opacity: 0;
306 | }
307 |
308 | /* Mimicking the 'Give feedback' button for UX consistency */
309 | .sidebar-search-container input[type=submit] {
310 | color: #FFFFFF;
311 | border: 2px solid #D6410D;
312 | padding: var(--sidebar-search-input-spacing-vertical) var(--sidebar-search-input-spacing-horizontal);
313 | background: #D6410D;
314 | font-weight: bold;
315 | font-size: var(--font-size--small);
316 | cursor: pointer;
317 | }
318 |
319 | .sidebar-search-container input[type=submit]:hover {
320 | text-decoration: underline;
321 | }
322 |
323 | /* Make inline code the same size as code blocks */
324 | p code.literal {
325 | border: 0;
326 | font-size: var(--code-font-size);
327 | }
328 |
--------------------------------------------------------------------------------
/docs/explanation/package-model.rst:
--------------------------------------------------------------------------------
1 | Package model
2 | =============
3 |
4 | Because :term:`Ubuntu` is based on the community-driven :term:`Debian` project,
5 | Ubuntu uses the Debian packaging model/format.
6 |
7 | This consists of :ref:`source packages ` and
8 | :ref:`binary packages `.
9 |
10 | .. _SourcePackages:
11 |
12 | Source packages
13 | ---------------
14 |
15 | A source package contains the :term:`source ` material used to
16 | build one or more binary packages.
17 |
18 | A source package is composed of:
19 |
20 | - a Debian Source Control (:file:`.dsc`) file,
21 | - one or more compressed tar files, and
22 | - optionally additional files depending on the type and format of the source
23 | package.
24 |
25 | The **Source Control** file contains metadata about the source package, for
26 | instance, a list of additional files, name and version, list of the binary
27 | packages it produces, dependencies, a :term:`digital signature `
28 | and many more fields.
29 |
30 | .. note::
31 |
32 | The :doc:`basic overview of the debian/ directory `
33 | article showcases the layout of an unpacked source package.
34 |
35 | Source package formats
36 | ~~~~~~~~~~~~~~~~~~~~~~
37 |
38 | There are multiple formats for how the source is packaged. The format of a
39 | source package is declared in the :file:`debian/source/format` file. This file
40 | should always exist. If this file can not be found, the :ref:`format 1.0 `
41 | is assumed for backwards compatibility, but :manpage:`lintian(1)` will warn you
42 | about it when you try to build a source package.
43 |
44 | .. tip::
45 |
46 | We strongly recommend to use the :ref:`3.0 (quilt) ` format
47 | for new packages.
48 |
49 | You should only pick a different format if you **really** know what you are doing.
50 |
51 | .. _NativeSourcePackages:
52 |
53 | Native source packages
54 | ^^^^^^^^^^^^^^^^^^^^^^
55 |
56 | In most cases, a software project is packaged by external contributors called the
57 | :term:`maintainers ` of the package. Because the packaging is often done
58 | by a 3rd-party (from the perspective of the software project), the software to be
59 | packaged is often not designed to be packaged. In these cases the source package
60 | has to do modifications to solve specific problems for its target
61 | :term:`distribution `. The source package can, in these cases, be
62 | considered as its own software project, like a :term:`fork `. Consequently,
63 | the :term:`Upstream` releases and source package releases do not
64 | always align.
65 |
66 | Native packages almost always originate from software projects designed with
67 | Debian packaging in mind and have no independent existence outside its target
68 | distribution. Consequently native packages do not differentiate between Upstream
69 | releases and source package releases. Therefore, the version identifier of a native
70 | package does not have an Debian-specific component.
71 |
72 | For example:
73 |
74 | - The `debhelper package`_ (provides tools for building Debian packages) is a native
75 | package from Debian. Because it is designed with packaging in mind, the packaging
76 | specific files are part of the original :term:`source code `. The
77 | debhelper developers are also maintainers of the Debian package. The Debian debhelper
78 | package gets merged into the Ubuntu debhelper package and has therefore a ``ubuntu``
79 | suffix in the version identifier.
80 | - In contrast, the `Ubuntu bash package`_ (the default :term:`shell ` on
81 | Ubuntu) is **NOT** a native package. The `bash Software`_ originates from the
82 | :term:`GNU project `. The bash releases of the GNU project project will get
83 | packaged by Debian maintainers and the `Debian bash package`_ is merged into the
84 | Ubuntu bash package by Ubuntu maintainers. The Debian and Ubuntu packages both
85 | are effectively their own separate software projects maintained by other people
86 | than the developers of the software that gets packaged. This is the process how
87 | most software is packaged on Ubuntu.
88 |
89 | .. warning::
90 |
91 | Although native packages sound like the solution to use for your software project
92 | if you want to distribute your software to Ubuntu/Debian, we **strongly** recommend
93 | against using native package formats for new packages. Native packages are known
94 | to cause long-term maintenance problems.
95 |
96 | .. _SourcePackageFormat_3.0quilt:
97 |
98 | Format: ``3.0 (quilt)``
99 | ^^^^^^^^^^^^^^^^^^^^^^^
100 |
101 | A new-generation source package format that records modifications in a
102 | :manpage:`quilt(1)` :term:`Patch` series within the :file:`debian/patches`
103 | folder. The patches are organised as a :term:`stack `, and you can apply,
104 | unapply, and update them easily by traversing the stack (push/pop). These
105 | changes are automatically applied during the extraction of the source package.
106 |
107 | A source package in this format contains at least an original tarball
108 | (``.orig.tar.ext`` where ``ext`` can be ``gz``, ``bz2``, ``lzma`` or ``xz``)
109 | and a debian tarball (``.debian.tar.ext``). It can also contain additional
110 | original tarballs (``.orig-component.tar.ext``), where ``component`` can only
111 | contain alphanumeric (``a-z``, ``A-Z``, ``0-9``) characters and hyphens (``-``).
112 | Optionally, each original tarball can be accompanied by a
113 | :term:`detached signature ` from the upstream project
114 | (``.orig.tar.ext.asc`` and ``.orig-component.tar.ext.asc``).
115 |
116 | For example, take a look at the ``hello`` package:
117 |
118 | .. code:: bash
119 |
120 | pull-lp-source --download-only 'hello' '2.10-3'
121 |
122 | .. note::
123 |
124 | You need to install ``ubuntu-dev-tools`` to run the :command:`pull-lp-source`:
125 |
126 | .. code:: bash
127 |
128 | sudo apt install ubuntu-dev-tools
129 |
130 | When you now run :manpage:`ls(1)`:
131 |
132 | .. code:: bash
133 |
134 | ls -1 hello_*
135 |
136 | you should see the following files:
137 |
138 | - :file:`hello_2.10-3.dsc`: The **Debian Source Control** file of the source package.
139 | - :file:`hello_2.10.orig.tar.gz`: The tarball containing the original source code
140 | of the upstream project.
141 | - :file:`hello_2.10.orig.tar.gz.asc`: The detached upstream signature of
142 | :file:`hello_2.10.orig.tar.gz`.
143 | - :file:`hello_2.10-3.debian.tar.xz`: The tarball containing the content of the
144 | Debian directory.
145 |
146 | .. _SourcePackageFormat_3.0native:
147 |
148 | Format: ``3.0 (native)``
149 | ^^^^^^^^^^^^^^^^^^^^^^^^
150 |
151 | A new-generation source package format extends the native package format defined
152 | in the :ref:`format 1.0 `.
153 |
154 | A source package in this format is a tarball (``.tar.ext`` where ``ext``
155 | can be ``gz``, ``bz2``, ``lzma`` or ``xz``).
156 |
157 | For example, let's take a look at the ``debhelper`` package:
158 |
159 | .. code:: bash
160 |
161 | pull-lp-source --download-only 'debhelper' '13.11.6ubuntu1'
162 |
163 | When you now run :manpage:`ls(1)`:
164 |
165 | .. code:: bash
166 |
167 | ls -1 debhelper_*
168 |
169 | you should see the following files:
170 |
171 | - ``debhelper_13.11.6ubuntu1.dsc``: The **Debian Source Control** file of the source package.
172 | - ``debhelper_13.11.6ubuntu1.tar.xz``: The tarball containing the source code of the project.
173 |
174 | Other examples of native source packages are:
175 |
176 | - `ubuntu-dev-tools `_
177 | - `ubuntu-release-upgrader `_
178 | - `dh-cargo `_
179 | - `ubiquity `_
180 | - `subiquity `_
181 |
182 | .. _SourcePackageFormat_1.0:
183 |
184 | Format: ``1.0``
185 | ^^^^^^^^^^^^^^^
186 |
187 | The original source package format. Nowadays, this format is rarely used.
188 |
189 | A native source package in this format consists of a single ``.tar.gz``
190 | file containing the source.
191 |
192 | A non-native source package in this format consists of a ``.orig.tar.gz`` file
193 | (containing the Upstream source) associated with a ``.diff.gz`` file (the patch
194 | containing Debian packaging modifications). Optionally, the original tarball
195 | can be accompanied by a detached Upstream signature ``.orig.tar.gz.asc``.
196 |
197 | .. note::
198 |
199 | This format does not specify a patch system, which makes it harder for
200 | :term:`maintainers ` to track modifications. There were multiple
201 | approaches to how packages tracked patches. Therefore, the source packages of
202 | this format often contained a :file:`debian/README.source` file explaining
203 | how to use the patch system.
204 |
205 | ``3.0`` formats improvements
206 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
207 |
208 | Some of the improvements that apply to most ``3.0`` formats are:
209 |
210 | - Support for additional compression formats: ``bzip2``, ``lzma`` and ``xz``.
211 | - Support for multiple Upstream tarballs.
212 | - Supports inclusion of binary files.
213 | - Debian-specific changes are no longer stored in a single ``.diff.gz``.
214 | - The Upstream tarball does not need to be repacked to strip the Debian directory.
215 |
216 | Other formats
217 | ^^^^^^^^^^^^^
218 |
219 | The following formats are rarely used, experimental and/or historical.
220 | You should only choose these if you know what you are doing.
221 |
222 | - ``3.0 (custom)``: Doesn't represent an actual source package format but can
223 | be used to create source packages with arbitrary files.
224 | - ``3.0 (git)``: An experimental format to package from a :term:`git` repository.
225 | - ``3.0 (bzr)``: An experimental format to package from a :term:`Bazaar` repository.
226 | - ``2.0``: The first specification of a new-generation source package format.
227 | It was never widely adopted and eventually replaced by
228 | :ref:`3.0 (quilt) `.
229 |
230 | ``.changes`` file
231 | ~~~~~~~~~~~~~~~~~
232 |
233 | Although technically not part of a source package -- every time a source package
234 | is built, a :file:`.changes` file will be created alongside it. The :file:`.changes`
235 | file contains metadata from the Source Control file and other information (e.g.
236 | the latest changelog entry) about the source package. :term:`Archive` tools and
237 | :term:`Archive Administrators ` use this data to process changes
238 | to source packages and determine the appropriate action to upload the source
239 | package to the :term:`Ubuntu Archive`.
240 |
241 | .. _BinaryPackages:
242 |
243 | Binary packages
244 | ---------------
245 |
246 | A **binary package** is a standardised format that the :term:`Package Manager`
247 | (:manpage:`dpkg(1)` or :manpage:`apt(8)`) can understand to install and
248 | uninstall software on a target machine. This simplifies distributing software
249 | to a target machine and managing the software on that machine.
250 |
251 | A Debian binary package uses the :file:`.deb` file extension and contains a set
252 | of files that will be installed on the host system and a set of files that
253 | control how the files will be installed or uninstalled.
254 |
255 | Resources
256 | ---------
257 |
258 | - `Debian policy manual v4.6.2.0 -- Chapter 3. Binary packages `_
259 | - `Debian policy manual v4.6.2.0 -- Chapter 4. Source packages `_
260 | - The manual page :manpage:`dpkg-source(1)`
261 | - `Debian wiki -- 3.0 source package format `_
262 |
263 | .. _debhelper package: https://launchpad.net/ubuntu/+source/debhelper
264 | .. _bash Software: https://www.gnu.org/software/bash/
265 | .. _Debian bash package: https://tracker.debian.org/pkg/bash
266 | .. _Ubuntu bash package: https://launchpad.net/ubuntu/+source/bash
267 |
--------------------------------------------------------------------------------
/docs/Makefile:
--------------------------------------------------------------------------------
1 | # Minimal makefile for Sphinx documentation
2 | #
3 |
4 | # You can set these variables from the command line, and also
5 | # from the environment for the first two.
6 | SPHINXOPTS ?= -c . -d .sphinx/.doctrees
7 | SPHINXBUILD ?= sphinx-build
8 | SPHINXDIR = .sphinx
9 | SOURCEDIR = .
10 | BUILDDIR = _build
11 | VENVDIR = $(SPHINXDIR)/venv
12 | PA11Y = $(SPHINXDIR)/node_modules/pa11y/bin/pa11y.js
13 | VENV = $(VENVDIR)/bin/activate
14 | SHELL = /usr/bin/bash
15 |
16 | .PHONY: full-help help distro-info-install woke-install pa11y-install install \
17 | run html epub serve clean clean-doc spelling linkcheck woke pa11y \
18 | pdf pdf-prep pdf-prep-force Makefile
19 |
20 | # Put it first so that "make" without argument is like "make help".
21 | help:
22 | @echo "\n" \
23 | "--------------------------------------------------------------- \n" \
24 | "* watch, build and serve the documentation: make run \n" \
25 | "* only build: make html \n" \
26 | "* only serve: make serve \n" \
27 | "* clean built doc files: make clean-doc \n" \
28 | "* clean full environment: make clean \n" \
29 | "* check links: make linkcheck \n" \
30 | "* check spelling: make spelling \n" \
31 | "* check inclusive language: make woke \n" \
32 | "* check accessibility: make pa11y \n" \
33 | "* build PDF: make pdf \n" \
34 | "* force install packages for PDF generation: make pdf-prep-force \n" \
35 | "* other possible targets: make \n" \
36 | "--------------------------------------------------------------- \n"
37 |
38 | full-help: $(VENVDIR)
39 | @. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
40 | @echo "\n\033[1;31mNOTE: This help texts shows unsupported targets!\033[0m"
41 | @echo "Run 'make help' to see supported targets."
42 |
43 | $(SPHINXDIR)/requirements.txt: distro-info-install
44 | python3 build_requirements.py
45 |
46 | # If requirements are updated, venv should be rebuilt and timestamped.
47 | $(VENVDIR): $(SPHINXDIR)/requirements.txt
48 | @echo "... setting up virtualenv"
49 | python3 -m venv --system-site-packages $(VENVDIR)
50 | . $(VENV); pip install --require-virtualenv \
51 | --upgrade -r $(SPHINXDIR)/requirements.txt \
52 | --log $(VENVDIR)/pip_install.log
53 | @test ! -f $(VENVDIR)/pip_list.txt || \
54 | mv $(VENVDIR)/pip_list.txt $(VENVDIR)/pip_list.txt.bak
55 | @. $(VENV); pip list --local --format=freeze > $(VENVDIR)/pip_list.txt
56 | @touch $(VENVDIR)
57 |
58 | distro-info-install:
59 | if (dpkg --status python3-distro-info | grep installed); then \
60 | echo "Skip installing python3-distro-info, because it is already installed."; \
61 | else \
62 | echo "Installing python3-distro-info..."; \
63 | sudo apt-get update; \
64 | sudo apt-get install --assume-yes python3-distro-info; \
65 | fi
66 |
67 | woke-install:
68 | @type woke >/dev/null 2>&1 || \
69 | { echo "Installing \"woke\" snap... \n"; sudo snap install woke; }
70 |
71 | pa11y-install:
72 | @type $(PA11Y) >/dev/null 2>&1 || { \
73 | echo "Installing \"pa11y\" from npm... \n"; \
74 | mkdir -p $(SPHINXDIR)/node_modules/ ; \
75 | npm install --prefix $(SPHINXDIR) pa11y; \
76 | }
77 |
78 | install: $(VENVDIR) woke-install
79 |
80 | run: install
81 | . $(VENV); sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
82 |
83 | # Doesn't depend on $(BUILDDIR) to rebuild properly at every run.
84 | html: install
85 | . $(VENV); $(SPHINXBUILD) -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w .sphinx/warnings.txt $(SPHINXOPTS)
86 |
87 | epub: install
88 | . $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w .sphinx/warnings.txt $(SPHINXOPTS)
89 |
90 | serve: html
91 | cd "$(BUILDDIR)"; python3 -m http.server 8000
92 |
93 | clean: clean-doc
94 | @test ! -e "$(VENVDIR)" -o -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)"
95 | rm -rf $(VENVDIR)
96 | rm -f .sphinx/requirements.txt
97 |
98 | clean-doc:
99 | git clean -fx "$(BUILDDIR)"
100 | rm -rf .sphinx/.doctrees
101 |
102 | spelling: html
103 | . $(VENV) ; python3 -m pyspelling -c .sphinx/spellingcheck.yaml -j $(shell nproc)
104 |
105 | linkcheck: install
106 | . $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
107 |
108 | woke: woke-install
109 | woke *.rst **/*.rst --exit-1-on-failure \
110 | -c https://github.com/canonical/Inclusive-naming/raw/main/config.yml
111 |
112 | pa11y: pa11y-install html
113 | find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y)
114 |
115 | # Standard PDF generation checks for system packages and provides context if not found
116 |
117 | pdf-prep: install
118 | @. $(VENV); (dpkg-query -W -f='$${Status}' latexmk 2>/dev/null | grep -c "ok installed" >/dev/null && echo "Package latexmk is installed") || (echo "PDF generation requires the installation of the following packages: latexmk fonts-freefont-otf fonts-ibm-plex texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng" && echo "" && echo "make pdf-prep-force will install these packages" && echo "" && echo "Please be aware these packages will be installed to your system" && false)
119 | @. $(VENV); (dpkg-query -W -f='$${Status}' fonts-freefont-otf 2>/dev/null | grep -c "ok installed" >/dev/null && echo "Package fonts-freefont-otf is installed") || (echo "PDF generation requires the installation of the following packages: latexmk fonts-freefont-otf fonts-ibm-plex texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng" && echo "" && echo "make pdf-prep-force will install these packages" && echo "" && echo "Please be aware these packages will be installed to your system" && false)
120 | @. $(VENV); (dpkg-query -W -f='$${Status}' fonts-ibm-plex 2>/dev/null | grep -c "ok installed" >/dev/null && echo "Package fonts-ibm-plex is installed") || (echo "PDF generation requires the installation of the following packages: latexmk fonts-freefont-otf fonts-ibm-plex texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng" && echo "" && echo "make pdf-prep-force will install these packages" && echo "" && echo "Please be aware these packages will be installed to your system" && false)
121 | @. $(VENV); (dpkg-query -W -f='$${Status}' texlive-latex-recommended 2>/dev/null | grep -c "ok installed" >/dev/null && echo "Package texlive-latex-recommended is installed") || (echo "PDF generation requires the installation of the following packages: latexmk fonts-freefont-otf fonts-ibm-plex texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng" && echo "" && echo "make pdf-prep-force will install these packages" && echo "" && echo "Please be aware these packages will be installed to your system" && false)
122 | @. $(VENV); (dpkg-query -W -f='$${Status}' texlive-latex-extra 2>/dev/null | grep -c "ok installed" >/dev/null && echo "Package texlive-latex-extra is installed") || (echo "PDF generation requires the installation of the following packages: latexmk fonts-freefont-otf fonts-ibm-plex texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng" && echo "" && echo "make pdf-prep-force will install these packages" && echo "" && echo "Please be aware these packages will be installed to your system" && false)
123 | @. $(VENV); (dpkg-query -W -f='$${Status}' texlive-fonts-recommended 2>/dev/null | grep -c "ok installed" >/dev/null && echo "Package texlive-fonts-recommended is installed") || (echo "PDF generation requires the installation of the following packages: latexmk fonts-freefont-otf fonts-ibm-plex texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng" && echo "" && echo "make pdf-prep-force will install these packages" && echo "" && echo "Please be aware these packages will be installed to your system" && false)
124 | @. $(VENV); (dpkg-query -W -f='$${Status}' texlive-font-utils 2>/dev/null | grep -c "ok installed" >/dev/null && echo "Package texlive-font-utils is installed") || (echo "PDF generation requires the installation of the following packages: latexmk fonts-freefont-otf fonts-ibm-plex texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng" && echo "" && echo "make pdf-prep-force will install these packages" && echo "" && echo "Please be aware these packages will be installed to your system" && false)
125 | @. $(VENV); (dpkg-query -W -f='$${Status}' texlive-lang-cjk 2>/dev/null | grep -c "ok installed" >/dev/null && echo "Package texlive-lang-cjk is installed") || (echo "PDF generation requires the installation of the following packages: latexmk fonts-freefont-otf fonts-ibm-plex texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng" && echo "" && echo "make pdf-prep-force will install these packages" && echo "" && echo "Please be aware these packages will be installed to your system" && false)
126 | @. $(VENV); (dpkg-query -W -f='$${Status}' texlive-xetex 2>/dev/null | grep -c "ok installed" >/dev/null && echo "Package texlive-xetex is installed") || (echo "PDF generation requires the installation of the following packages: latexmk fonts-freefont-otf fonts-ibm-plex texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng" && echo "" && echo "make pdf-prep-force will install these packages" && echo "" && echo "Please be aware these packages will be installed to your system" && false)
127 | @. $(VENV); (dpkg-query -W -f='$${Status}' plantuml 2>/dev/null | grep -c "ok installed" >/dev/null && echo "Package plantuml is installed") || (echo "PDF generation requires the installation of the following packages: latexmk fonts-freefont-otf fonts-ibm-plex texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng" && echo "" && echo "make pdf-prep-force will install these packages" && echo "" && echo "Please be aware these packages will be installed to your system" && false)
128 | @. $(VENV); (dpkg-query -W -f='$${Status}' xindy 2>/dev/null | grep -c "ok installed" >/dev/null && echo "Package xindy is installed") || (echo "PDF generation requires the installation of the following packages: latexmk fonts-freefont-otf fonts-ibm-plex texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng" && echo "" && echo "make pdf-prep-force will install these packages" && echo "" && echo "Please be aware these packages will be installed to your system" && false)
129 | @. $(VENV); (dpkg-query -W -f='$${Status}' tex-gyre 2>/dev/null | grep -c "ok installed" >/dev/null && echo "Package tex-gyre is installed") || (echo "PDF generation requires the installation of the following packages: latexmk fonts-freefont-otf fonts-ibm-plex texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng" && echo "" && echo "make pdf-prep-force will install these packages" && echo "" && echo "Please be aware these packages will be installed to your system" && false)
130 | @. $(VENV); (dpkg-query -W -f='$${Status}' dvipng 2>/dev/null | grep -c "ok installed" >/dev/null && echo "Package dvipng is installed") || (echo "PDF generation requires the installation of the following packages: latexmk fonts-freefont-otf fonts-ibm-plex texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng" && echo "" && echo "make pdf-prep-force will install these packages" && echo "" && echo "Please be aware these packages will be installed to your system" && false)
131 |
132 | # Entrypoint to install system packages, separate from usual workflow due to permanence
133 |
134 | pdf-prep-force:
135 | apt-get update
136 | apt-get install --no-install-recommends -y latexmk fonts-freefont-otf fonts-ibm-plex texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng \
137 |
138 | pdf: pdf-prep
139 | . $(VENV); sphinx-build -M latexpdf "$(SOURCEDIR)" "_build" $(SPHINXOPTS)
140 | rm ./_build/latex/front-page-light.pdf || true
141 | rm ./_build/latex/normal-page-footer.pdf || true
142 | find ./_build/latex -name "*.pdf" -exec mv -t ./ {} +
143 | rm -r _build
144 |
145 | # Catch-all target: route all unknown targets to Sphinx using the new
146 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
147 | %: Makefile
148 | . $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
149 |
--------------------------------------------------------------------------------
/docs/tutorial/make-changes-to-package.rst:
--------------------------------------------------------------------------------
1 | Making changes to a package
2 | ===========================
3 |
4 | This tutorial goes through the process of adding a patch to a package in Ubuntu. Specifically, we add a command-line option to the :command:`hello` command, which greets a user using their username. This covers topics like :command:`git-ubuntu`, :command:`quilt`, and changelogs.
5 |
6 | Getting the tools
7 | -----------------
8 |
9 | We are using a :command:`git-ubuntu` workflow. Install it with :command:`snap`:
10 |
11 | .. prompt:: none $ auto
12 |
13 | $ sudo snap install --classic git-ubuntu
14 |
15 | Once we have :command:`git-ubuntu` installed, use it to fetch the source code for the :pkg:`hello` package in Ubuntu:
16 |
17 | .. prompt:: none $ auto
18 |
19 | $ git-ubuntu clone hello
20 | $ cd hello/
21 |
22 | We are using some tools from the :pkg:`ubuntu-dev-tools` package. Install it with:
23 |
24 | .. prompt:: none $ auto
25 |
26 | $ sudo apt install -y ubuntu-dev-tools
27 |
28 | Understanding the package
29 | -------------------------
30 |
31 | Initially, we have the ``ubuntu/devel`` branch checked out. At the time of writing this tutorial, the development series is ``plucky``, so the ``ubuntu/devel`` branch is in line with the ``plucky`` version.
32 |
33 | Let's explore the packaging we are dealing with. In the :file:`debian` directory, there are files like :file:`changelog`, :file:`rules`, :file:`control`, and more. Everything outside of the :file:`debian` directory is from the original upstream source. In :file:`debian/source/format`, we see:
34 |
35 | .. code-block:: text
36 |
37 | 3.0 (quilt)
38 |
39 | This means that, like most packages, this package uses the :command:`quilt` tool to manage patches to the upstream source code. So, even though we are using Git to track our changes to the *packaging*, we need to use a :command:`quilt` patch to maintain the changes required for our new command-line option.
40 |
41 | In particular, instead of ending up with a Git commit that modifies the upstream source code directly, our commit adds a new file, :file:`debian/patches/add-username-command-line-option.patch`, which contains the patch to apply to the upstream source code.
42 |
43 | Creating a patch with :command:`quilt`
44 | --------------------------------------
45 |
46 |
47 | First, create the new patch file using :command:`quilt`:
48 |
49 | .. prompt:: none $ auto
50 |
51 | $ QUILT_PATCHES=debian/patches quilt new add-username-command-line-option.patch
52 | Patch add-username-command-line-option.patch is now on top
53 |
54 | This should create a new, empty file: :file:`debian/patches/add-username-command-line-option.patch`. And it adds a corresponding entry to the :file:`debian/patches/series` file. Once that is done, start writing the patch. For each source file that is modified by our patch, we need to tell :command:`quilt` about it. In this case:
55 |
56 | .. prompt:: none $ auto
57 |
58 | $ quilt add src/hello.c
59 |
60 | After that, edit the source normally using our favorite text editor. To see our progress, use the usual Git tools to see the diff. So, after adding the new command line flag, the diff might look like:
61 |
62 | .. code-block:: diff
63 |
64 | $ git diff -- src/hello.c
65 | diff --git a/src/hello.c b/src/hello.c
66 | index 453962f..f1ccf0a 100644
67 | --- a/src/hello.c
68 | +++ b/src/hello.c
69 | @@ -23,6 +23,10 @@
70 | #include "error.h"
71 | #include "progname.h"
72 | #include "xalloc.h"
73 | +#include "unistd.h"
74 | +#include "sys/types.h"
75 | +#include "pwd.h"
76 | +#include "limits.h"
77 |
78 | static const struct option longopts[] = {
79 | {"greeting", required_argument, NULL, 'g'},
80 | @@ -44,6 +48,8 @@ main (int argc, char *argv[])
81 | const char *greeting_msg;
82 | wchar_t *mb_greeting;
83 | size_t len;
84 | + struct passwd *pwd = NULL;
85 | + char user_greeting[sizeof("hello, !") + LOGIN_NAME_MAX] = {};
86 |
87 | set_program_name (argv[0]);
88 |
89 | @@ -65,7 +71,7 @@ main (int argc, char *argv[])
90 | This is implemented in the Gnulib module "closeout". */
91 | atexit (close_stdout);
92 |
93 | - while ((optc = getopt_long (argc, argv, "g:htv", longopts, NULL)) != -1)
94 | + while ((optc = getopt_long (argc, argv, "g:htvu", longopts, NULL)) != -1)
95 | switch (optc)
96 | {
97 | /* --help and --version exit immediately, per GNU coding standards. */
98 | @@ -83,6 +89,15 @@ main (int argc, char *argv[])
99 | case 't':
100 | greeting_msg = _("hello, world");
101 | break;
102 | + case 'u':
103 | + errno = 0;
104 | + pwd = getpwuid(geteuid());
105 | + if (!pwd)
106 | + error (EXIT_FAILURE, errno, _("failed to get user name"));
107 | +
108 | + snprintf(user_greeting, sizeof(user_greeting), "hello, %s!", pwd->pw_name);
109 | + greeting_msg = _(user_greeting);
110 | + break;
111 | default:
112 | lose = 1;
113 | break;
114 |
115 | To save these changes in our quilt patch, we need to *refresh* the patch:
116 |
117 | .. prompt:: none $ auto
118 |
119 | $ quilt refresh -p ab --no-timestamps --no-index
120 |
121 | It is good practice to add `DEP-3 headers `_ to patches to add additional context, such as the origin, author, and related bugs. The :command:`quilt` tool has a helper for this:
122 |
123 | .. prompt:: none $ auto
124 |
125 | $ quilt header -e --dep3
126 |
127 | This opens a text editor with pre-populated text: ::
128 |
129 | Description:
130 |
131 | Author:
132 | Origin: ,
133 | Bug:
134 | Bug-:
135 | Forwarded:
136 | Applied-Upstream:
137 | Reviewed-by:
138 | Last-Update: 2025-04-23
139 | ---
140 | This patch header follows DEP-3: http://dep.debian.net/deps/dep3/
141 |
142 | Not everything here needs to be filled in. In this case, our headers might look like: ::
143 |
144 | Description: Add -u command line option to hello
145 | This command line option adds a username-specific greeting. E.g.,
146 | $ hello -u
147 | hello, user123!
148 | Author: Nick Rosbrook
149 | Forwarded: no, Ubuntu only
150 | Last-Update: 2025-04-23
151 | ---
152 | This patch header follows DEP-3: http://dep.debian.net/deps/dep3/
153 |
154 | Our final patch should look something like:
155 |
156 | .. code-block:: diff
157 |
158 | Description: Add -u command line option to hello
159 | This command line option adds a username-specific greeting. E.g.,
160 | $ hello -u
161 | hello, user123!
162 | Author: Nick Rosbrook
163 | Forwarded: no, Ubuntu only
164 | Last-Update: 2025-04-23
165 | ---
166 | This patch header follows DEP-3: http://dep.debian.net/deps/dep3/
167 | --- a/src/hello.c
168 | +++ b/src/hello.c
169 | @@ -23,6 +23,10 @@
170 | #include "error.h"
171 | #include "progname.h"
172 | #include "xalloc.h"
173 | +#include "unistd.h"
174 | +#include "sys/types.h"
175 | +#include "pwd.h"
176 | +#include "limits.h"
177 |
178 | static const struct option longopts[] = {
179 | {"greeting", required_argument, NULL, 'g'},
180 | @@ -44,6 +48,8 @@
181 | const char *greeting_msg;
182 | wchar_t *mb_greeting;
183 | size_t len;
184 | + struct passwd *pwd = NULL;
185 | + char user_greeting[sizeof("hello, !") + LOGIN_NAME_MAX] = {};
186 |
187 | set_program_name (argv[0]);
188 |
189 | @@ -65,7 +71,7 @@
190 | This is implemented in the Gnulib module "closeout". */
191 | atexit (close_stdout);
192 |
193 | - while ((optc = getopt_long (argc, argv, "g:htv", longopts, NULL)) != -1)
194 | + while ((optc = getopt_long (argc, argv, "g:htvu", longopts, NULL)) != -1)
195 | switch (optc)
196 | {
197 | /* --help and --version exit immediately, per GNU coding standards. */
198 | @@ -83,6 +89,15 @@
199 | case 't':
200 | greeting_msg = _("hello, world");
201 | break;
202 | + case 'u':
203 | + errno = 0;
204 | + pwd = getpwuid(geteuid());
205 | + if (!pwd)
206 | + error (EXIT_FAILURE, errno, _("failed to get user name"));
207 | +
208 | + snprintf(user_greeting, sizeof(user_greeting), "hello, %s!", pwd->pw_name);
209 | + greeting_msg = _(user_greeting);
210 | + break;
211 | default:
212 | lose = 1;
213 | break;
214 |
215 | The patch is currently applied in the working directory.
216 |
217 | * To un-apply: :command:`quilt pop -a`
218 | * To apply again: :command:`quilt push -a`
219 |
220 | Committing the changes
221 | ----------------------
222 |
223 | Now that we have created our patch file, track the changes in Git. Add the new patch file (and in this case, the newly created :file:`debian/patches/series` file) to the Git index and commit the change:
224 |
225 | .. prompt:: none $ auto
226 |
227 | $ git add debian/patches/
228 | $ git commit -m "debian/patches: add a new -u command line option to hello"
229 |
230 | Next, some housekeeping changes:
231 |
232 | #. Make sure that the ``Maintainer:`` field in :file:`debian/control` is set correctly.
233 |
234 | #. Add a new entry to :file:`debian/changelog` explaining our changes and incrementing the package version number.
235 |
236 | To update the maintainer field, use the :command:`update-maintainer` tool from the :pkg:`ubuntu-dev-tools` package. In this case, the field is already set correctly, so we should see:
237 |
238 | .. prompt:: none $ auto
239 |
240 | $ update-maintainer
241 | The Maintainer email is set to an ubuntu.com address. Doing nothing.
242 |
243 | If a change was made, commit that change with:
244 |
245 | .. prompt:: none $ auto
246 |
247 | $ git commit -m "update maintainer" -- debian/control
248 |
249 | Once you have either updated the maintainer, or confirmed that it is already correct, update the changelog. The :command:`dch` tool helps with this. If you run :command:`dch -i`, you see something like this in your text editor: ::
250 |
251 | hello (2.10-3ubuntu1) UNRELEASED; urgency=medium
252 |
253 | *
254 |
255 | -- Nick Rosbrook Tue, 22 Apr 2025 17:03:03 -0400
256 |
257 | hello (2.10-3build2) oracular; urgency=medium
258 |
259 | * No-change rebuild to bump version in oracular.
260 |
261 | -- Marc Deslauriers Mon, 27 May 2024 07:18:24 -0400
262 |
263 | hello (2.10-3build1) noble; urgency=high
264 |
265 | * No change rebuild for 64-bit time_t and frame pointers.
266 |
267 | -- Julian Andres Klode Mon, 08 Apr 2024 17:58:52 +0200
268 |
269 | [...SNIP...]
270 |
271 | The :command:`dch` tool has done a few things:
272 |
273 | 1. Created a new empty changelog entry.
274 | 2. Set the author line using your name, email, and the current date and time.
275 | 3. Updated the package version number to ``2.10-3ubuntu1``.
276 | 4. Set the release name to ``UNRELEASED``.
277 |
278 | Our job now is to fill in the entry and explain our changes. In this case, write something like: ::
279 |
280 | hello (2.10-3ubuntu1) plucky; urgency=medium
281 |
282 | * debian/patches: add a new -u command line option to hello
283 |
284 | -- Nick Rosbrook Tue, 22 Apr 2025 17:03:03 -0400
285 |
286 | Once you are happy with the changelog entry, commit the change:
287 |
288 | .. prompt:: none $ auto
289 |
290 | $ git commit -m "update changelog" -- debian/changelog
291 |
292 | At this point, we should have two (or three if :command:`update-maintainer` was needed) commits: one adding our new patch, and another updating the changelog:
293 |
294 | .. prompt:: none $ auto
295 |
296 | $ git log
297 | commit a62e1590cc6a12925c8fe9bce49d9b7f5834468e (HEAD -> ubuntu/devel)
298 | Author: Nick Rosbrook
299 | Date: Wed Apr 23 10:04:32 2025 -0400
300 |
301 | update changelog
302 |
303 | commit d6ef1607ce6163e6a611c591e94f478c2c06a35a
304 | Author: Nick Rosbrook
305 | Date: Tue Apr 22 16:24:39 2025 -0400
306 |
307 | debian/patches: add a new -u command line option to hello
308 |
309 | commit fd73db6d7406ee1fb8512a5b54c259f3b3368eab (tag: pkg/import/2.10-3build2, pkg/ubuntu/plucky-devel, pkg/ubuntu/plucky, pkg/ubuntu/oracular-proposed, pkg/ubuntu/oracular-devel, pkg/ubuntu/oracular, pkg/ubuntu/devel, pkg/HEAD)
310 | Author: Marc Deslauriers
311 | Date: Mon May 27 07:18:24 2024 -0400
312 |
313 | 2.10-3build2 (patches unapplied)
314 |
315 | Imported using git-ubuntu import.
316 |
317 | Notes (changelog):
318 | * No-change rebuild to bump version in oracular.
319 |
320 | And that's it! We have successfully:
321 |
322 | * Added a new patch to this package.
323 | * Documented our change.
324 | * Prepared the package for its next upload to the Ubuntu archive.
325 |
326 | Next steps
327 | ----------
328 |
329 | From here, there are many options for testing our patch before proposing the change in a merge proposal:
330 |
331 | * Build and test the package locally using :command:`sbuild` and :command:`autopkgtest`.
332 | * Upload to a PPA and test from there.
333 |
334 | Once you feel confident that the patch is working correctly, open a merge proposal and request :ref:`sponsorship` for your change.
335 |
--------------------------------------------------------------------------------
10 |
{{ project }} 11 |12 | 13 |
14 |
15 |
18 |
19 |