Merge ~jugmac00/launchpad-buildd:introduce-diataxis-framework into launchpad-buildd:master

[Jürgen Gmach]

Introduce the Diátaxis documentation framework

[Ioana Lasc (ilasc)]

review: Approve

diff --git a/docs/deployment.rst b/docs/explanation/deployment.rst
 similarity index 100%
 rename from docs/deployment.rst
 rename to docs/explanation/deployment.rst
diff --git a/docs/building.rst b/docs/how-to/building.rst
 similarity index 85%
 rename from docs/building.rst
 rename to docs/how-to/building.rst
index 4893bb8..280b2b7 100644
--- a/docs/building.rst
+++ b/docs/how-to/building.rst
@@ -1,5 +1,5 @@
-Building the project
-********************
+How to build the project
+************************
 
 In order to build the package you need ``dpkg-dev`` and ``fakeroot``.
 
diff --git a/docs/how-to/changelog_entry.rst b/docs/how-to/changelog_entry.rst
 new file mode 100644
index 0000000..ac00da1
--- /dev/null
+++ b/docs/how-to/changelog_entry.rst
@@ -0,0 +1,20 @@
+
+How to create a changelog entry
+*******************************
+
+Prerequisites
+-------------
+
+.. code:: bash
+
+    sudo apt install devscripts
+
+Create the changelog entry
+--------------------------
+
+In order to create a changelog entry in ``debian/changelog``,
+you need to run the following command:
+
+.. code:: bash
+
+    dch -U
diff --git a/docs/how-to/deployment.rst b/docs/how-to/deployment.rst
 new file mode 100644
index 0000000..a52be76
--- /dev/null
+++ b/docs/how-to/deployment.rst
@@ -0,0 +1,29 @@
+How to deploy launchpad-buildd
+******************************
+
+The following steps need to be performed before `Upgrading the builders
+<https://wiki.canonical.com/InformationInfrastructure/ISO/BuildInfrastructure/BuilddFixing>`_.
+
+1. Ensure everything has been merged to master.
+
+2. Create a new release branch, based on master.
+
+3. Run ``DEBEMAIL="<email address>" DEBFULLNAME="<name>" dch -rD bionic``.
+   The later recipe build will prepend the correct preamble for each Ubuntu release.
+
+4. Commit and push this branch, open a MergeProposal for review.
+
+5. Once the release branch has merged to master,
+   tag the release commit and check https://code.launchpad.net/~launchpad/+recipe/launchpad-buildd-daily
+   for the recipe build to happen.
+   You can start a build if required.
+
+6. Upgrade the dogfood builders
+   (you may need someone on the LP team with permissions to help with this;
+   see `documentation <https://wiki.canonical.com/InformationInfrastructure/ISO/BuildInfrastructure/BuilddFixing#Upgrading_launchpad-buildd_in_scalingstack>`_).
+
+7. Perform QA
+
+8. File an upgrade RT (`sample <https://portal.admin.canonical.com/C135751>`_),
+   noting the version number and possibly multiple suites/releases
+   (`IS procedure <https://wiki.canonical.com/InformationInfrastructure/ISO/BuildInfrastructure/BuilddFixing>`_).
diff --git a/docs/developing.rst b/docs/how-to/developing.rst
 similarity index 78%
 rename from docs/developing.rst
 rename to docs/how-to/developing.rst
index 1db8095..895d0a7 100644
--- a/docs/developing.rst
+++ b/docs/how-to/developing.rst
@@ -1,5 +1,5 @@
-Developing
-**********
+How to set up a development environment
+***************************************
 
 First of all, it is recommended that you create an lxc container, since the
 following steps will make changes in your system. And since some build types
@@ -29,13 +29,3 @@ test suite both in python2 and python3.
 More information on how to integrate it with Launchpad can be found here:
 https://dev.launchpad.net/Soyuz/HowToDevelopWithBuildd
 
-
-Creating a changelog entry
---------------------------
-
-In order to create a changelog entry in ``debian/changelog``,
-you need to run ``dch`` from the ``devscripts`` package.
-
-.. code:: bash
-
-    dch -U
diff --git a/docs/how-to/qa.rst b/docs/how-to/qa.rst
 new file mode 100644
index 0000000..e226d9a
--- /dev/null
+++ b/docs/how-to/qa.rst
@@ -0,0 +1,11 @@
+How to perform QA
+*****************
+
+Depending on the applied changes,
+you may need to perform the following build types:
+
+1. `TranslationTemplates <https://dev.launchpad.net/Translations/GenerateTemplatesOnTestServers>`_
+2. Source Package Recipe Build
+3. OCI Image Build
+4. Snap Build
+5. Binary Package Build 
diff --git a/docs/index.rst b/docs/index.rst
index 427c800..f8ae1de 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -20,6 +20,24 @@ See https://dev.launchpad.net/ for more context.
    :maxdepth: 2
 
    self
-   developing
-   building
-   deployment
+
+How-to guides
+-------------
+
+.. toctree::
+   :maxdepth: 1
+
+   how-to/developing
+   how-to/changelog_entry
+   how-to/building
+   how-to/deployment
+   how-to/qa
+
+
+Explanation
+-----------
+
+.. toctree::
+   :maxdepth: 1
+
+   explanation/deployment