Installing checkbox tutorial (#626)

* Installing checkbox tutorial

* Minor: typo

* Review feedback

* Reference required by install snap

Minor: fixed links in install

* Forgotten snap reference file

* Fixed spelling

Minor: sorted wordlist.txt in alphabetical order, to do the same
  you can use the following in vim: ":%!sort"

* Change default/encouraged version to classic

* Implemented docs feedback

Uppercase C in checkbox
Link to installation in reference
Ubuntu is not code
blob -> blog
Uppercase S in snapcraft
CI expanded to Continuous Integration
Typos and grammar

docs/.sphinx/wordslist.txt

@@ -1,5 +1,6 @@
 APIs
 autoconf
+backend
 baz
 Baz
 bluetooth
@@ -26,6 +27,8 @@ ESC
 Fi
 FooBar
 formatter
+frontend
+frontends
 github
 GitHub
 GPLv
@@ -46,6 +49,7 @@ JUnit
 keypresses
 libre
 loopback
+LTS
 lv
 mis
 miscellanea
@@ -74,7 +78,10 @@ rtc
 RTC
 runtime
 SIGINT
+snapcraft
 Snapcraft
+Snapcraft
+SRU
 SRU
 SSID
 startprovider

docs/reference/index.rst

@@ -8,3 +8,4 @@ Reference
    stack
    launcher
    units/index
+   snaps

docs/reference/snaps.rst

@@ -0,0 +1,76 @@
+.. _snap_reference:
+
+===============
+Snap Versions
+===============
+
+There are several Checkbox snaps and channels to choose from. You can
+get a full list via ``snap info checkbox``. You can refer to the following
+to decide what you should install.
+
+.. _ref_which_snap:
+
+Picking your version
+====================
+
+As you may recall from the :ref:`installing_checkbox` tutorial, when installing Checkbox
+you need to pick a frontend and a backend. There are several parameters that
+may influence your choice of the best snap for your situation but in general
+there are three distinguishing factors in Checkbox snaps: base, confinement and
+stability.
+
+Base
+----
+
+The base of a snap is the underlying version of the operating system
+that it uses to run. For example ``checkbox 22.04`` and ``checkbox22``
+are built on top of Ubuntu 22.04. This is not an 100% accurate
+explanation of what a base is but you can use this rule of thumb in your decision.
+If you want a more complete explanation of what bases are and how they are built,
+refer to this
+`blog post from the Snapcraft team <https://snapcraft.io/blog/all-about-that-base>`_.
+
+In general we advise to use the version of Checkbox that most closely matches the
+system that is going to run it. If you are not on an LTS release of Ubuntu or
+you are using a completely different operating system, try to match it to
+the closest release we have. For example, if you are on Ubuntu 23.04,
+``checkbox22`` is probably the one you will have to choose.
+
+Confinement
+-----------
+
+As you may know, or may learn more from
+`the Snapcraft documentation <https://snapcraft.io/docs/snap-confinement>`_, a
+snap can either use ``strict`` or ``classic`` confinement. Checkbox has a snap
+for both models. The strict snaps are called ``ucXX``, the classic ones have a
+standard LTS name.
+
+In general we advise to use ``classic`` snap. You are going to need the ``classic``
+one whenever the tests you are running need a binary that is available in your
+system but not in the ``strict`` snap.
+
+.. note::
+
+  This section only applies to the Checkbox frontend, the backend snap is always
+  ``strictly`` confined.
+
+Stability
+---------
+
+Checkbox uses `semantic versioning <https://semver.org>`_. There are three channels
+that you can install from ``edge``, ``beta`` and ``stable``.
+
+If you want a stable version that we are pretty sure that works, use ``stable``, this
+version was tested thoroughly via continuous integration and in our lab and is the
+one that we use for our `Ubuntu Certified <https://ubuntu.com/certified>`_ program.
+
+If you can trade a little bit of stability for more up-to-date features, you can use
+``beta``. This version of Checkbox was tested via CI and on a subset of our lab. It
+should be as good as ``stable``, but once we are sure it is we will promote it to
+that channel.
+
+If you want the most up-to-date possible build of Checkbox you can use the
+``edge`` channel. These builds are updated daily and contain the latest changes to
+the framework. We do not advise to use this channel in production, it is tested
+via CI and it is built from the latest commit in the ``main`` branch of the
+`Checkbox Repository on github <https://github.com/canonical/checkbox>`_.

docs/tutorial/using-checkbox/installing_checkbox.rst

@@ -0,0 +1,49 @@
+.. _installing_checkbox:
+
+===================
+Installing Checkbox
+===================
+
+In order to install Checkbox you are going to need two parts, a ``runtime``
+and a ``frontend``.
+
+First we need to install the ``runtime``, this tutorial will use the ``checkbox22``
+runtime on Ubuntu 22.04. We also offer versions for ``16``, ``18`` and ``20``.
+Use the one that matches your Ubuntu version or refer to :ref:`ref_which_snap` to
+understand and pick the one that fits your needs::
+
+   $ sudo snap install checkbox22
+   [...]
+   checkbox22 X.Y.Z from Canonical Certification Team (ce-certification-qa) installed
+
+Now that we have the ``checkbox22`` runtime, we need a ``frontend``, to install it
+run the following::
+
+  $ sudo snap install checkbox --channel 22.04/stable --classic
+  [...]
+  checkbox (22.04/stable) X.Y.Z from Canonical Certification Team (ce-certification-qa) installed
+
+.. note::
+  There are multiple frontends as you may discover by typing ``snap info checkbox``.
+  If you are unsure about what ``frontend`` you should use, consider
+  reading this page: :ref:`ref_which_snap`, but for the scope of this tutorial the one
+  installed in this snipped is enough.
+
+Now that we have installed both we can launch Checkbox running:
+
+.. code-block:: none
+
+  $ checkbox.checkbox-cli
+  Select test plan
+  ┌─────────────────────────────────────────────────────────────────────────────────────┐
+  │ ( ) (Deprecated) Fully Automatic Client Certification Tests                         │
+  │ ( ) 18.04 Server Certification Full                                                 │
+  │ ( ) 18.04 Server Certification Functional                                           │
+  │ ( ) 18.04 System On Chip Certification (For SoC Testing)                            │
+  │ ( ) 18.04 Virtual Machine Full (For Hypervisors)                                    │
+  │ ( ) 20.04 Server Certification Full                                                 │
+  └─────────────────────────────────────────────────────────────────────────────────────┘
+  Press <Enter> to continue                                                      (H) Help
+
+If your screen is similar to this one, rejoice! You can start using
+Checkbox! For now you can close it using ``Ctrl+C``.