doc: west 0.12 docs

Update the documentation for this release.

Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>

.github/workflows/doc-build.yml

@@ -26,7 +26,7 @@ on:
 
 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

doc/guides/west/index.rst

@@ -26,7 +26,7 @@ You can run ``west --help`` (or ``west -h`` for short) to get top-level help
 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::

doc/guides/west/manifest.rst

@@ -288,6 +288,10 @@ next.
        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 @@ Here, ``west update`` will recursively initialize and update just the
 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

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
 *******
 

doc/guides/west/west-apis.rst

@@ -304,6 +304,9 @@ Manifest and sub-objects
    .. versionadded:: 0.9.0
       The *group_filter* and *submodules* attributes.
 
+   .. versionadded:: 0.12.0
+      The *userdata* attribute.
+
    Constructor:
 
    .. automethod:: __init__