From 55308d0a61cfba5c7895985c4dca79ca0bd2a5ef Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20Kl=C3=B6tzke?= <jan@kloetzke.net>
Date: Fri, 1 Nov 2024 21:28:11 +0100
Subject: [PATCH] doc: document mangedLayers policy
---
doc/manual/configuration.rst | 4 +++
doc/manual/policies.rst | 54 ++++++++++++++++++++++++++++++++++++
2 files changed, 58 insertions(+)
diff --git a/doc/manual/configuration.rst b/doc/manual/configuration.rst
index e7b86645..56689a3a 100644
--- a/doc/manual/configuration.rst
+++ b/doc/manual/configuration.rst
@@ -1968,6 +1968,10 @@ possibility is to provide an SCM-Dictionary (see
commit: ...
- bsp
+.. note::
+ Managed layers are only supported if the :ref:`policies-managedLayers`
+ policy is set to the new behaviour.
+
If a layer SCM specification is given, Bob takes care of the layer management:
- Layers are checked out / updated during bob-build (except build-only).
diff --git a/doc/manual/policies.rst b/doc/manual/policies.rst
index 7dbd1503..9e07dcb5 100644
--- a/doc/manual/policies.rst
+++ b/doc/manual/policies.rst
@@ -290,6 +290,60 @@ Old behavior
New behavior
Apply string substitution to ``metaEnvironment`` variables.
+.. _policies-managedLayers:
+
+managedLayers
+~~~~~~~~~~~~~
+
+Introduced in: 0.25
+
+Starting with Bob version 0.25, managed layers are supported. This changed the
+location where layers are stored, though. Historically, layers could be nested
+where they would form a tree structure. That is, each layer can have a ``layers``
+directory itself where further layers are located. Because this does not work
+if multiple layers refer to another common layer, the directory structure
+has been flattened.
+
+Old behavior
+ Keep support for projects that were created before Bob 0.25. Layers with
+ sub-layers form a tree structure. See the following example::
+
+ .
+ ├── config.yaml
+ ├── layers
+ │ └── foo
+ │ ├── config.yaml
+ │ ├── layers
+ │ │ ├── bar
+ │ │ │ └── recipes
+ │ │ └── baz
+ │ │ └── recipes
+ │ └── recipes
+ └── recipes
+
+ No SCM can be used in the :ref:`configuration-config-layers` section of
+ ``config.yaml``. The :ref:`manpage-layers` command will refuse to work on
+ such projectes.
+
+New behavior
+ Managed layers are supported, that is SCMs can be used in the
+ :ref:`configuration-config-layers` section of ``config.yaml``. The layers
+ are checked out flat into the ``layers`` directory of the project::
+
+ .
+ ├── config.yaml
+ ├── layers
+ │ ├── bar
+ │ │ └── recipes
+ │ ├── baz
+ │ │ └── recipes
+ │ └── foo
+ │ ├── config.yaml
+ │ └── recipes
+ └── recipes
+
+ Unmanaged layers are expected in the same directory.
+
.. _policies-obsolete:
Obsolete policies