doc: west 0.12 docs
Update the documentation for this release.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml
index 4adac6a..913cc38 100644
--- a/.github/workflows/doc-build.yml
+++ b/.github/workflows/doc-build.yml
@@ -26,7 +26,7 @@
env:
# NOTE: west docstrings will be extracted from the version listed here
- WEST_VERSION: 0.11.1
+ WEST_VERSION: 0.12.0
# The latest CMake available directly with apt is 3.18, but we need >=3.20
# so we fetch that through pip.
CMAKE_VERSION: 3.20.5
diff --git a/doc/guides/west/index.rst b/doc/guides/west/index.rst
index daab877..91a509f 100644
--- a/doc/guides/west/index.rst
+++ b/doc/guides/west/index.rst
@@ -26,7 +26,7 @@
for available west commands, and ``west <command> -h`` for detailed help on
each command.
-The following pages document west's ``v0.11.x`` releases, and provide additional
+The following pages document west's ``v0.12.x`` releases, and provide additional
context about the tool.
.. toctree::
diff --git a/doc/guides/west/manifest.rst b/doc/guides/west/manifest.rst
index 557151e..c82977b 100644
--- a/doc/guides/west/manifest.rst
+++ b/doc/guides/west/manifest.rst
@@ -288,6 +288,10 @@
submodules`_ defined by the project. See
:ref:`west-manifest-submodules` for details.
+ * - ``userdata``
+ - Optional. The value is an arbitrary YAML value. See
+ :ref:`west-project-userdata`.
+
.. _Git submodules: https://git-scm.com/book/en/v2/Git-Tools-Submodules
Defaults
@@ -1054,6 +1058,44 @@
submodules in ``foo`` with paths ``path/to/foo-first-sub`` and
``path/to/foo-second-sub``. Any submodules in ``bar`` are still ignored.
+.. _west-project-userdata:
+
+Project user data
+*****************
+
+West versions v0.12 and later support an optional ``userdata`` key in projects.
+It is meant for consumption by programs that require user-specific project
+metadata. Beyond parsing it as YAML, west itself ignores the value completely.
+
+The key's value is arbitrary YAML. West parses the value and makes it
+accessible to programs using :ref:`west-apis` as the ``userdata`` attribute of
+the corresponding ``west.manifest.Project`` object.
+
+Example manifest fragment:
+
+.. code-block:: yaml
+
+ manifest:
+ projects:
+ - name: foo
+ - name: bar
+ userdata: a-string
+ - name: baz
+ userdata:
+ key: value
+
+Example Python usage:
+
+.. code-block:: python
+
+ manifest = west.manifest.Manifest.from_file()
+
+ foo, bar, baz = manifest.get_projects(['foo', 'bar', 'baz'])
+
+ foo.userdata # None
+ bar.userdata # 'a-string'
+ baz.userdata # {'key': 'value'}
+
.. _west-manifest-import:
Manifest Imports
diff --git a/doc/guides/west/release-notes.rst b/doc/guides/west/release-notes.rst
index c885a99..ac75874 100644
--- a/doc/guides/west/release-notes.rst
+++ b/doc/guides/west/release-notes.rst
@@ -3,6 +3,27 @@
West Release Notes
##################
+v0.12.0
+*******
+
+New features:
+
+- West now works on the `MSYS2 <https://www.msys2.org/>`_ platform.
+
+- West manifest files can now contain arbitrary user data associated with each
+ project. See :ref:`west-project-userdata` for details.
+
+Bug fixes:
+
+- The ``west list`` command's ``{sha}`` format key has been fixed for
+ the manifest repository; it now prints ``N/A`` ("not applicable")
+ as expected.
+
+:ref:`API <west-apis>` changes:
+
+- The ``west.manifest.Project.userdata`` attribute was added to support
+ project user data.
+
v0.11.1
*******
diff --git a/doc/guides/west/west-apis.rst b/doc/guides/west/west-apis.rst
index 0ce468c..2a69c61 100644
--- a/doc/guides/west/west-apis.rst
+++ b/doc/guides/west/west-apis.rst
@@ -304,6 +304,9 @@
.. versionadded:: 0.9.0
The *group_filter* and *submodules* attributes.
+ .. versionadded:: 0.12.0
+ The *userdata* attribute.
+
Constructor:
.. automethod:: __init__
