[buildstream] 05/07: doc/source/porting_user_configuration.rst: Documenting breaking changes

[tv...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

tvb pushed a commit to branch tristan/porting-guide
in repository https://gitbox.apache.org/repos/asf/buildstream.git

commit f406682a3a0e7d0c0fcaa1682c9ca137d9a5da22
Author: Tristan van Berkom <tr...@codethink.co.uk>
AuthorDate: Fri Dec 31 15:04:24 2021 +0900

    doc/source/porting_user_configuration.rst: Documenting breaking changes
---
 doc/source/porting_user_configuration.rst | 39 +++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/doc/source/porting_user_configuration.rst b/doc/source/porting_user_configuration.rst
index f862da7..1971ddb 100644
--- a/doc/source/porting_user_configuration.rst
+++ b/doc/source/porting_user_configuration.rst
@@ -4,3 +4,42 @@
 
 Porting the buildstream.conf
 ============================
+This document outlines breaking changes made to the :ref:`user configuration <user_config>`
+in BuildStream 2.
+
+
+Filename and parallel installation
+----------------------------------
+The default filename to load user configuration remains unchanged, however,
+if you plan to install and use both versions of BuildStream on the same
+host, it is recommended to keep your BuildStream 2 configuration in a
+file named ``buildstream2.conf``.
+
+
+Working directories
+-------------------
+The ``builddir`` and ``artifactdir`` have been removed in favor of the new ``cachedir``.
+
+
+BuildStream 1:
+~~~~~~~~~~~~~~
+
+.. code:: yaml
+
+   builddir: ${XDG_CACHE_HOME}/buildstream/build
+   artifactdir: ${XDG_CACHE_HOME}/buildstream/artifacts
+
+
+BuildStream 2:
+~~~~~~~~~~~~~~
+
+.. code:: yaml
+
+   cachedir: ${XDG_CACHE_HOME}/buildstream/cache
+
+
+Remote cache configuration
+--------------------------
+The configuration for remote artifact caches has been completely
+redesigned, please refer to the :ref:`artifact cache configuration documentation <config_artifact_caches>`
+for details on how to configure remotes in BuildStream 2.