From 612409d39d86817009755adfa9ca628ea16fee4a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mart=C3=AD=20Bol=C3=ADvar?= <marti.bolivar@nordicsemi.no>
Date: Thu, 4 Nov 2021 06:13:37 -0700
Subject: [PATCH] doc: west 0.12 docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update the documentation for this release.

Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
---
 .github/workflows/doc-build.yml   |  2 +-
 doc/guides/west/index.rst         |  2 +-
 doc/guides/west/manifest.rst      | 42 +++++++++++++++++++++++++++++++
 doc/guides/west/release-notes.rst | 21 ++++++++++++++++
 doc/guides/west/west-apis.rst     |  3 +++
 5 files changed, 68 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml
index 4adac6ac972..913cc38c6f9 100644
--- a/.github/workflows/doc-build.yml
+++ b/.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
diff --git a/doc/guides/west/index.rst b/doc/guides/west/index.rst
index daab87797f9..91a509f0d0f 100644
--- a/doc/guides/west/index.rst
+++ b/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::
diff --git a/doc/guides/west/manifest.rst b/doc/guides/west/manifest.rst
index 557151eee84..c82977b831f 100644
--- a/doc/guides/west/manifest.rst
+++ b/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
diff --git a/doc/guides/west/release-notes.rst b/doc/guides/west/release-notes.rst
index c885a993c19..ac7587477f2 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 0ce468c8095..2a69c610ca8 100644
--- a/doc/guides/west/west-apis.rst
+++ b/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__