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: * `A ReStructuredText Primer `_ * `Quick reStructuredText `_ 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 `_ 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).