Merge ~jugmac00/launchpad:add-how-to-qa-turnip-api-changes into launchpad:master

[Jürgen Gmach]

Add `How-to qa turnip API changes`

[Jürgen Gmach (jugmac00)]

Thanks for the first review - let's have a quick discussion on Monday whether the information fits in here, or whether we want to create new repo for the "Launchpad project" documentation.

Unmerged commits

903f0be... by Jürgen Gmach on 2022-01-21

Add `How-to qa turnip API changes`

Also the section header was renamed to `How-to guides`, according to the
new documentation system we are following, see https://diataxis.fr/

diff --git a/doc/guides/how-to-qa-turnip-api-changes.rst b/doc/guides/how-to-qa-turnip-api-changes.rst
 new file mode 100644
index 0000000..11b5f82
--- /dev/null
+++ b/doc/guides/how-to-qa-turnip-api-changes.rst
@@ -0,0 +1,94 @@
+============================
+How-to qa turnip API changes
+============================
+
+qa is usually performed on https://qastaging.launchpad.net.
+
+Prerequisites
+=============
+
+- You need access to ``launchpad-bastion-ps5.internal``
+
+- Your user needs to be able to sudo into ``stg-launchpad-git``
+
+- You need to have ``lp-shell`` installed in your development environment
+
+Access to above host and the sudo permission are granted by
+`IS <https://portal.admin.canonical.com/new/>`_.
+
+``lp-shell`` can be installed via
+
+.. code-block:: bash
+
+    sudo apt install lptools
+
+Perform qa
+==========
+
+- Pick a project on https://qastaging.launchpad.net, e.g.
+  https://qastaging.launchpad.net/turnip
+
+- From above project, pick one git repository, and get its ``repo id`` via
+
+  .. code-block:: bash
+
+     $ lp-shell qastaging devel
+
+     >>> lp.git_repositories.getByPath(path='~canonical-launchpad-branches/turnip/+git/turnip').id
+     3683
+
+  This id will be used for building the query,
+  e.g. for querying the commit API (``/repo/<id>/commits>``).
+
+- Turn on company VPN
+
+- Log into the bastion host
+
+  .. code-block:: bash
+
+     $ ssh launchpad-bastion-ps5.internal
+
+- Switch to the service user
+
+  .. code-block:: bash
+
+     ubuntu@juju-a7beac-stg-launchpad-git-7:~$ sudo -iu stg-launchpad-git
+
+- Get an overview of the available staging servers via Juju
+
+  .. code-block:: bash
+
+     $ stg-launchpad-git@launchpad-bastion-ps5:~$ juju status
+
+     ...
+
+     turnip-api ...
+     turnip-celery ...
+     turnip-pack...
+
+- Log into one of the API servers
+
+  .. code-block:: bash
+
+     stg-launchpad-git@launchpad-bastion-ps5:~$ juju ssh turnip-api/0
+
+- Perform the query
+
+  .. code-block:: bash
+
+     $ curl \
+     -H "Content-Type: application/json" \
+     -d '{"commits": ["180ad564a7297ee61fbdfe70fdf53d95febd1e09"], "filter_paths": ["config.yaml"]}' \
+     http://0.0.0.0:19417/repo/3683/commits
+
+     $ <results>
+
+- <optional> You can inspect the turnip logs in ``/srv/turnip/logs/``.
+
+Further steps
+=============
+
+Once the changes are verified,
+you can mark the corresponding commit on https://deployable.ols.canonical.com/project/turnip as deployable.
+
+And finally, the changes `can be deployed <https://wiki.canonical.com/InformationInfrastructure/WebOps/LP/LaunchpadGitDeployment#Code_upgrade>`_!
diff --git a/doc/index.rst b/doc/index.rst
index 2fa2b59..dc76c5f 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -30,12 +30,13 @@ Tutorials
 
    running
 
-Guides
-======
+How-to guides
+=============
 
 .. toctree::
    :maxdepth: 1
 
+   guides/how-to-qa-turnip-api-changes
    guides/architecture
    guides/python
    guides/tests