Merge branch 'tristan/install-guide-refactoring' into 'master'

Install guide refactoring

See merge request BuildStream/buildstream!733

4 files changed, 322 insertions, 257 deletions

diff --git a/doc/source/install_linux_distro.rst b/doc/source/install_linux_distro.rst
index 8a0d536e0..a547d4e8c 100644
--- a/doc/source/install_linux_distro.rst
+++ b/doc/source/install_linux_distro.rst
@@ -1,264 +1,16 @@
 
-.. _install:
-
-Installing BuildStream on a Linux distro
-========================================
-BuildStream requires the following base system requirements:
-
-* python3 >= 3.5
-* bubblewrap >= 0.1.2
-* fuse2
-
-BuildStream also depends on the host tools for the :mod:`Source <buildstream.source>` plugins.
-Refer to the respective :ref:`source plugin <plugins_sources>` documentation for host tool
-requirements of specific plugins.
-
-The default plugins with extra host dependencies are:
-
-* bzr
-* deb
-* git
-* ostree
-* patch
-* tar
-
-If you intend to push built artifacts to a remote artifact server,
-which requires special permissions, you will also need:
-
-* ssh
-
-
-Installing from source (recommended)
-------------------------------------
-Until BuildStream is available in your distro, you will need to install
-it yourself from the `git repository <https://gitlab.com/BuildStream/buildstream.git>`_
-using python's ``pip`` package manager.
-
-For the purpose of installing BuildStream while there are no distro packages,
-you will additionally need:
-
-* pip for python3 (only required for setup)
-* Python 3 development libraries and headers
-* git (to checkout buildstream)
-
-
-Installing dependencies
-~~~~~~~~~~~~~~~~~~~~~~~
-
-
-Arch Linux
-++++++++++
-Install the dependencies with::
-
-  sudo pacman -S \
-      python fuse2 bubblewrap \
-      python-pip git
-
-For the default plugins::
-
-  sudo pacman -S \
-      bzr git lzip ostree patch python-gobject
-
-
-The package *python-arpy* is required by the deb source plugin. This is not
-obtainable via `pacman`, you must get *python-arpy* from AUR:
-https://aur.archlinux.org/packages/python-arpy/
-
-To install::
-
-  wget https://aur.archlinux.org/cgit/aur.git/snapshot/python-arpy.tar.gz
-  tar -xvf python-arpy.tar.gz
-  cd python-arpy
-  makepkg -si
-
-Debian
-++++++
-Install the dependencies with::
-
-  sudo apt-get install \
-      python3 fuse bubblewrap \
-      python3-pip python3-dev git
-
-For the default plugins:
-
-Stretch
-^^^^^^^
-With stretch, you first need to ensure that you have the backports repository
-setup as described `here <https://backports.debian.org/Instructions/>`_
-
-By adding the following line to your sources.list::
-
-  deb http://deb.debian.org/debian stretch-backports main
-
-And then running::
-
-  sudo apt update
-
-At this point you should be able to get the system requirements for the default plugins with::
-
-  sudo apt install \
-      bzr git lzip patch python3-arpy python3-gi
-  sudo apt install -t stretch-backports \
-      gir1.2-ostree-1.0 ostree
-
-Buster or Sid
-^^^^^^^^^^^^^
-For debian unstable or testing, only the following line should be enough
-to get the system requirements for the default plugins installed::
-
-  sudo apt-get install \
-      lzip gir1.2-ostree-1.0 git bzr ostree patch python3-arpy python3-gi
-
-
-Fedora
-++++++
-For recent fedora systems, the following line should get you the system
-requirements you need::
-
-  dnf install -y \
-      python3 fuse bubblewrap \
-      python3-pip python3-devel git
-
-For the default plugins::
-
-  dnf install -y \
-      bzr git lzip patch ostree python3-gobject
-  pip3 install --user arpy
-
-
-Ubuntu
-++++++
-
-Ubuntu 18.04 LTS or later
-^^^^^^^^^^^^^^^^^^^^^^^^^
-Install the dependencies with::
-
-  sudo apt install \
-      python3 fuse bubblewrap \
-      python3-pip python3-dev git
-
-For the default plugins::
-
-  sudo apt install \
-      bzr gir1.2-ostree-1.0 git lzip ostree patch python3-arpy python3-gi
-
-Ubuntu 16.04 LTS
-^^^^^^^^^^^^^^^^
-On Ubuntu 16.04, neither `bubblewrap <https://github.com/projectatomic/bubblewrap/>`_
-or `ostree <https://github.com/ostreedev/ostree>`_ are available in the official repositories.
-You will need to install them in whichever way you see fit. Refer the the upstream documentation
-for advice on this.
-
-
-Installing
-~~~~~~~~~~
-Once you have the base system dependencies, you can install the BuildStream
-python package as a regular user.
-
-Via PyPI (recommended)
-++++++++++++++++++++++
-::
-
-  pip3 install --user BuildStream
-
-This will install latest stable version of BuildStream and its pure python
-dependencies into your user's homedir in ``~/.local``.
-
-Keep following the instructions below to ensure that the ``bst``
-command is in your ``PATH`` and to enable bash completions for it.
-
-.. note::
-
-  If you want a specific version of BuildStream, you can install it using
-  ``pip install --user BuildStream==<version-number>``
-
-Via Git checkout
-++++++++++++++++
-::
-
-  git clone https://gitlab.com/BuildStream/buildstream.git
-  cd buildstream
-  pip3 install --user -e .
-
-This will install buildstream's pure python dependencies into
-your user's homedir in ``~/.local`` and will run BuildStream directly
-from the git checkout directory.
-
-Keep following the instructions below to ensure that the ``bst``
-command is in your ``PATH`` and to enable bash completions for it.
-
-.. note::
-
-   We recommend the ``-e`` option because you can upgrade your
-   installation by simply updating the checked out git repository.
-
-   If you want a full installation that is not linked to your
-   git checkout, just omit the ``-e`` option from the above commands.
-
-
-Adjust PATH
-~~~~~~~~~~~
-Since BuildStream is now installed under your local user's install directories,
-you need to ensure that ``PATH`` is adjusted.
-
-A regular way to do this is to add the following line to the end of your ``~/.bashrc``::
-
-  export PATH="${PATH}:${HOME}/.local/bin"
-
-.. note::
-
-   You will have to restart your terminal in order for these changes to take effect.
-
-
-Bash completions
-~~~~~~~~~~~~~~~~
-Bash completions are supported by sourcing the ``buildstream/data/bst``
-script found in the BuildStream repository. On many systems this script
-can be installed into a completions directory but when installing BuildStream
-without a package manager this is not an option.
-
-To enable completions for an installation of BuildStream you
-installed yourself from git, just append the script verbatim
-to your ``~/.bash_completion``:
-
-.. literalinclude:: ../../buildstream/data/bst
-   :language: yaml
-
-
-Upgrading BuildStream
-~~~~~~~~~~~~~~~~~~~~~
-
-Via PyPI
-++++++++
-
-If you installed BuildStream from PyPI, you can update it like so::
-
-  pip install --user --upgrade BuildStream
-
-Via Git checkout
-++++++++++++++++
-
-If you installed BuildStream from a local git checkout using ``-e`` option, all
-you need to do to upgrade BuildStream is to update your local git checkout::
-
-  cd /path/to/buildstream
-  git pull --rebase
-
-If you did not specify the ``-e`` option at install time or the dependancies
-have changed, you will need to cleanly reinstall BuildStream::
-
-  pip3 uninstall buildstream
-  cd /path/to/buildstream
-  git pull --rebase
-  pip3 install --user .
 
+.. _install_linux_distro:
 
 Installing from distro packages
--------------------------------
+===============================
+BuildStream is available on some linux distributions, here are
+some install instructions for the linux distributions which
+have packaged BuildStream.
 
 
 Arch Linux
-~~~~~~~~~~
+----------
 Packages for Arch exist in `AUR <https://wiki.archlinux.org/index.php/Arch_User_Repository#Installing_packages>`_.
 Two different package versions are available:
 
@@ -267,8 +19,7 @@ Two different package versions are available:
 
 
 Fedora
-~~~~~~
-
+------
 BuildStream is not yet in the official Fedora repositories, but you can
 install it from a Copr::
 
diff --git a/doc/source/install_source.rst b/doc/source/install_source.rst
new file mode 100644
index 000000000..5fa0c0603
--- /dev/null
+++ b/doc/source/install_source.rst
@@ -0,0 +1,288 @@
+
+
+Installing from source
+======================
+Until BuildStream is available in :ref:`your distro <install_linux_distro>`, you will
+need to install it yourself from source.
+
+
+Installing dependencies
+-----------------------
+Before installing BuildStream from source, it is necessary to first install
+the system dependencies. Below are some linux distribution specific instructions
+for installing these dependencies.
+
+BuildStream requires the following base system requirements:
+
+* python3 >= 3.5
+* bubblewrap >= 0.1.2
+* fuse2
+
+BuildStream also depends on the host tools for the :mod:`Source <buildstream.source>` plugins.
+Refer to the respective :ref:`source plugin <plugins_sources>` documentation for host tool
+requirements of specific plugins.
+
+The default plugins with extra host dependencies are:
+
+* bzr
+* deb
+* git
+* ostree
+* patch
+* tar
+
+If you intend to push built artifacts to a remote artifact server,
+which requires special permissions, you will also need:
+
+* ssh
+
+
+Arch Linux
+~~~~~~~~~~
+Install the dependencies with::
+
+  sudo pacman -S \
+      python fuse2 bubblewrap \
+      python-pip
+
+For the default plugins::
+
+  sudo pacman -S \
+      bzr git lzip ostree patch python-gobject
+
+
+The package *python-arpy* is required by the deb source plugin. This is not
+obtainable via `pacman`, you must get *python-arpy* from AUR:
+https://aur.archlinux.org/packages/python-arpy/
+
+To install::
+
+  wget https://aur.archlinux.org/cgit/aur.git/snapshot/python-arpy.tar.gz
+  tar -xvf python-arpy.tar.gz
+  cd python-arpy
+  makepkg -si
+
+
+Debian
+~~~~~~
+Install the dependencies with::
+
+  sudo apt-get install \
+      python3 fuse bubblewrap \
+      python3-pip python3-dev
+
+For the default plugins:
+
+
+Stretch
++++++++
+With stretch, you first need to ensure that you have the backports repository
+setup as described `here <https://backports.debian.org/Instructions/>`_
+
+By adding the following line to your sources.list::
+
+  deb http://deb.debian.org/debian stretch-backports main
+
+And then running::
+
+  sudo apt update
+
+At this point you should be able to get the system requirements for the default plugins with::
+
+  sudo apt install \
+      bzr git lzip patch python3-arpy python3-gi
+  sudo apt install -t stretch-backports \
+      gir1.2-ostree-1.0 ostree
+
+
+Buster or Sid
++++++++++++++
+For debian unstable or testing, only the following line should be enough
+to get the system requirements for the default plugins installed::
+
+  sudo apt-get install \
+      lzip gir1.2-ostree-1.0 git bzr ostree patch python3-arpy python3-gi
+
+
+Fedora
+~~~~~~
+For recent fedora systems, the following line should get you the system
+requirements you need::
+
+  dnf install -y \
+      python3 fuse bubblewrap \
+      python3-pip python3-devel
+
+For the default plugins::
+
+  dnf install -y \
+      bzr git lzip patch ostree python3-gobject
+  pip3 install --user arpy
+
+
+Ubuntu
+~~~~~~
+
+
+Ubuntu 18.04 LTS or later
++++++++++++++++++++++++++
+Install the dependencies with::
+
+  sudo apt install \
+      python3 fuse bubblewrap \
+      python3-pip python3-dev
+
+For the default plugins::
+
+  sudo apt install \
+      bzr gir1.2-ostree-1.0 git lzip ostree patch python3-arpy python3-gi
+
+
+Ubuntu 16.04 LTS
+++++++++++++++++
+On Ubuntu 16.04, neither `bubblewrap <https://github.com/projectatomic/bubblewrap/>`_
+or `ostree <https://github.com/ostreedev/ostree>`_ are available in the official repositories.
+You will need to install them in whichever way you see fit. Refer the the upstream documentation
+for advice on this.
+
+
+Installing
+----------
+Once you have the base system dependencies, you can install the BuildStream
+python package as a regular user.
+
+
+Installing from PyPI (recommended)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Since we only ever publish :ref:`release versions <install_semantic_versioning>` on
+PyPI, it is currently recommended to use this installation path. This will
+ensure that you always have the latest recommended version of BuildStream that
+we recommend.
+
+To install from PyPI, you will additionally require:
+
+* pip for python3 (only required for setup)
+* Python 3 development libraries and headers
+
+Simply run the following command::
+
+  pip3 install --user BuildStream
+
+This will install latest stable version of BuildStream and its pure python
+dependencies into your user's homedir in ``~/.local``.
+
+Keep following the instructions below to ensure that the ``bst``
+command is in your ``PATH`` and to enable bash completions for it.
+
+.. note::
+
+  If you want a specific version of BuildStream, you can install it using
+  ``pip install --user BuildStream==<version-number>``
+
+
+Upgrading from PyPI
++++++++++++++++++++
+Once you have already installed BuildStream from PyPI, you can later update
+to the latest recommended version like so::
+
+  pip install --user --upgrade BuildStream
+
+
+.. _install_git_checkout:
+
+Installing from a git checkout
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To install directly from the `git repository <https://gitlab.com/BuildStream/buildstream.git>`_
+using python's ``pip`` package manager, you will additionally require:
+
+* pip for python3 (only required for setup)
+* Python 3 development libraries and headers
+* git (to checkout BuildStream)
+
+Before installing, please check the existing tags in the git repository
+and determine which version you want to install, and whether you want
+to install an official release version (recommended), or a development snapshot
+to help us out testing the bleeding edge of development. Follow the
+:ref:`semantic versioning guide <install_semantic_versioning>` to determine
+which tag you intend to install.
+
+Run the following commands::
+
+  git clone https://gitlab.com/BuildStream/buildstream.git
+  cd buildstream
+  git checkout <desired release tag>
+  pip3 install --user -e .
+
+This will install buildstream's pure python dependencies into
+your user's homedir in ``~/.local`` and will run BuildStream directly
+from the git checkout directory.
+
+Keep following the instructions below to ensure that the ``bst``
+command is in your ``PATH`` and to enable bash completions for it.
+
+.. note::
+
+   We recommend the ``-e`` option because you can upgrade your
+   installation by simply updating the checked out git repository.
+
+   If you want a full installation that is not linked to your
+   git checkout, just omit the ``-e`` option from the above commands.
+
+
+Upgrading from a git checkout
++++++++++++++++++++++++++++++
+If you installed BuildStream from a local git checkout using ``-e`` option, all
+you need to do to upgrade BuildStream is to update your local git checkout::
+
+  cd /path/to/buildstream
+  git pull --rebase
+
+If you did not specify the ``-e`` option at install time or the dependancies
+have changed, you will need to cleanly reinstall BuildStream::
+
+  pip3 uninstall buildstream
+  cd /path/to/buildstream
+  git pull --rebase
+  pip3 install --user .
+
+.. note::
+
+   If BuildStream has added any dependencies since the last upgrade,
+   you will need to uninstall and reinstall to ensure those dependencies
+   are met, regardless of whether you have used the ``-e`` option at
+   install time.
+
+
+Post install setup
+------------------
+After having installed from source using any of the above methods, some
+setup will be required to use BuildStream.
+
+
+Adjust PATH
+~~~~~~~~~~~
+Since BuildStream is now installed under your local user's install directories,
+you need to ensure that ``PATH`` is adjusted.
+
+A regular way to do this is to add the following line to the end of your ``~/.bashrc``::
+
+  export PATH="${PATH}:${HOME}/.local/bin"
+
+.. note::
+
+   You will have to restart your terminal in order for these changes to take effect.
+
+
+Bash completions
+~~~~~~~~~~~~~~~~
+Bash completions are supported by sourcing the ``buildstream/data/bst``
+script found in the BuildStream repository. On many systems this script
+can be installed into a completions directory but when installing BuildStream
+without a package manager this is not an option.
+
+To enable completions for an installation of BuildStream you
+installed yourself from git, just append the script verbatim
+to your ``~/.bash_completion``:
+
+.. literalinclude:: ../../buildstream/data/bst
+   :language: yaml
diff --git a/doc/source/install_versions.rst b/doc/source/install_versions.rst
new file mode 100644
index 000000000..a82cb9dc7
--- /dev/null
+++ b/doc/source/install_versions.rst
@@ -0,0 +1,20 @@
+
+
+.. _install_semantic_versioning:
+
+Semantic Versioning
+===================
+BuildStream follows the Semantic Versioning Convention `(SemVer) <https://semver.org/>`_,
+and uses even minor point numbers to denote releases intended for users while
+odd minor point numbers represent development snapshops.
+
+For example, for a given version number ``X.Y.Z``
+ * The ``X.<even number>.*`` versions are releases intended for users.
+ * The ``X.<odd number>.*`` versions are development spanshots intended for testing.
+
+If you are :ref:`installing from git <install_git_checkout>`, please look for the latest
+tag in the latest release branch to ensure you're getting the latest release.
+
+Current release branches:
+ * `bst-1.2 (latest) <https://gitlab.com/BuildStream/buildstream/commits/bst-1.2>`_
+ * `bst-1.0 (deprecated) <https://gitlab.com/BuildStream/buildstream/commits/bst-1.0>`_
diff --git a/doc/source/main_install.rst b/doc/source/main_install.rst
index 1a4895903..a52c81512 100644
--- a/doc/source/main_install.rst
+++ b/doc/source/main_install.rst
@@ -1,3 +1,7 @@
+
+
+.. _install:
+
 Install
 =======
 This section covers how to install BuildStream onto your machine, how to run
@@ -9,8 +13,10 @@ BuildStream inside a docker image and also how to configure an artifact server.
    and macOS users should refer to :ref:`docker`.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
+   install_source
    install_linux_distro
    install_docker
    install_artifacts
+   install_versions