Caution

The Packaging and Development guide is currently undergoing a major overhaul to bring it up to date. The current state you are seeing now is a preview of this effort.

The current version is unstable (changing URLs can occur at any time) and most content is not in properly reviewed yet. Proceed with caution and be aware of technical inaccuracies.

If you are an experienced packager and would like to contribute, we would love for you to be involved! See our contribution page for details of how to join in.

Contribute to the Ubuntu Packaging Guide¶

The Ubuntu Packaging Guide is an open source project that warmly welcomes community contributions and suggestions.

This document describes how to contribute changes to the Ubuntu Packaging Guide. If you don’t already have a GitHub account, you can sign up on their website.

How to contribute¶

I want to raise an issue¶

We use GitHub issues to track things that need to be fixed. If you find a problem and want to report it to us, you can click on the “Give feedback” button at the top of any page in the Guide, and it will open an issue for you.

Alternatively, you can open an issue directly and describe the problem you’re having, or the suggestion you want to add.

I have a question about packaging¶

If you’re stuck and have a question, you can use our GitHub discussion board to ask, or start a discussion.

Note that we may not be able to respond immediately, so please be patient!

I want to submit a fix¶

If you found an issue and want to submit a fix for it, or have written a guide you would like to add to the documentation, feel free to open a pull request to submit your fix against our main branch. If you need help, please use the discussion board or contact one of the repository administrators.

Contribution format for the project¶

Sphinx & reStructuredText¶

The Guide is built using Sphinx. Articles should be written in reStructuredText. The following links might be helpful:

How to add a new Sphinx extension¶

In general, there are two places you will need to update to add new extensions.

docs/conf.py - add the name of the extension to the extensions configuration parameter
docs/.sphinx/requirements.txt - add the name of the extension to the bottom of the list

The documentation for most Sphinx extensions will tell you what text to add to the conf.py file, as in this example:

extensions = [
    'sphinx_copybutton',
    'sphinx_design',
]

Translations¶

We use the localisation (l10n) module for Sphinx and gettext for translating the Ubuntu Packaging Guide.

Some notes about translating the guide:

Some formatting is part of reStructuredText and should not be changed, including emphasis (which uses asterisks or underscores), paragraph ending before a code block (::) and double backtick quotes (``).
The Guide uses email-style reStructuredText links. If you see a link in the text like:
```
`Translatable link text <Link_Reference_>`_
```
Then replace the “Translatable link text” with your translations, but keep the Link_Reference unchanged (even if it is in English). The same applies if a URL is used instead of Link_Reference.

To test your translation, use make BUILDER-LANGUAGE command (for example, make html-it will build HTML docs in Italian language).