doc: west: add v0.6.1 documentation

West v0.6.1 has been released. The main feature is that "west update"
now avoids communicating with the network by default when project
revisions have already been fetched.

This allows for offline operation and significantly speeds up the
command (it's 10 times faster on my machine and home network).

There are other miscellaneous changes as well; document them also.

Signed-off-by: Marti Bolivar <[email protected]>

Author: mbolivar-nordic

doc/guides/west/config.rst

@@ -139,6 +139,13 @@ commands are documented in the pages for those commands.
      - String, relative path from the :term:`west installation` root directory
        to the manifest repository used by ``west update`` and other commands
        which parse the manifest. Set locally by ``west init``.
+   * - ``update.fetch``
+     - String, one of ``"smart"`` (the default behavior starting in v0.6.1) or
+       ``"always"`` (the previous behavior). If set to ``"smart"``, the
+       :ref:`west update <west-multi-repo-cmds>` command will skip fetching
+       from project remotes when those projects' revisions in the manifest file
+       are SHAs or tags which are already available locally. The ``"always"``
+       behavior is to unconditionally fetch from the remote.
    * - ``zephyr.base``
      - String, default value to set for the :envvar:`ZEPHYR_BASE` environment
        variable while the west command is running. By default, this is set to

doc/guides/west/release-notes.rst

@@ -1,7 +1,48 @@
 West Release Notes
 ##################
 
-v0.6.x
+v0.6.1
+******
+
+The user-visible features in this point release are:
+
+- The `west update <west-multi-repo-cmds>` command has a new ``--fetch``
+  command line flag and ``update.fetch`` :ref:`configuration option
+  <west-config>`. The default value, "smart", skips fetching SHAs and tags
+  which are available locally.
+- Better and more consistent error-handling in the ``west diff``, ``west
+  status``, ``west forall``, and ``west update`` commands. Each of these
+  commands can operate on multiple projects; if a subprocess related to one
+  project fails, these commands now continue to operate on the rest of the
+  projects. All of them also now report a nonzero error code from the west
+  process if any of these subprocesses fails (this was previously not true of
+  ``west forall`` in particular).
+- The :ref:`west manifest <west-multi-repo-misc>` command also handles errors
+  better.
+- The :ref:`west list <west-multi-repo-misc>` command now works even when the
+  projects are not cloned, as long as its format string only requires
+  information which can be read from the manifest file. It still fails if the
+  format string requires data stored in the project repository, e.g. if it
+  includes the ``{sha}`` format string key.
+- Commands and options which operate on git revisions now accept abbreviated
+  SHAs. For example, ``west init --mr SHA_PREFIX`` now works. Previously, the
+  ``--mr`` argument needed to be the entire 40 character SHA if it wasn't a
+  branch or a tag.
+
+The developer-visible changes to the :ref:`west-apis` are:
+
+- west.log.banner(): new
+- west.log.small_banner(): new
+- west.manifest.Manifest.get_projects(): new
+- west.manifest.Project.is_cloned(): new
+- west.commands.WestCommand instances can now access the parsed
+  Manifest object via a new self.manifest property during the
+  do_run() call. If read, it returns the Manifest object or
+  aborts the command if it could not be parsed.
+- west.manifest.Project.git() now has a capture_stderr kwarg
+
+
+v0.6.0
 ******
 
 - No separate bootstrapper

doc/guides/west/repo-tool.rst

@@ -155,6 +155,8 @@ This distribution also includes a launcher executable, also named ``west``. When
 west is installed, the launcher is placed by :file:`pip3` somewhere in the
 user's ``PATH``. This is the command-line entry point.
 
+.. _west-manifest-rev:
+
 The ``manifest-rev`` branch
 ***************************
 
@@ -223,13 +225,27 @@ important to understand.
      (``-m`` defaults to https://github.com/zephyrproject-rtos/zephyr, and
      the ``-mr`` default is overridden to ``v1.15.0``).
 
-- ``west update [--rebase] [--keep-descendants] [--exclude-west] [PROJECT
-  ...]``: clone and update the specified projects based
+- ``west update [--fetch {always,smart}] [--rebase] [--keep-descendants]
+  [PROJECT ...]``: clone and update the specified projects based
   on the current :term:`west manifest`.
 
-  This command parses the manifest, clones any project repositories that are
-  not already present locally, and checks out the project revisions specified
-  in the manifest file, updating ``manifest-rev`` branches along the way.
+  By default, this command:
+
+  #. Parses the manifest file, :file:`west.yml`
+  #. Clones any project repositories that are not already present locally
+  #. Fetches any project revisions in the manifest file which are not already
+     pulled from the remote
+  #. Sets each project's :ref:`manifest-rev <west-manifest-rev>` branch to the
+     current manifest revision
+  #. Checks out those revisions in local working trees
+
+  To operate on a subset of projects only, specify them using the ``PROJECT``
+  positional arguments, which can be either project names as given in the
+  manifest file, or paths to the local project clones.
+
+  To force this command to fetch from project remotes even if the revisions
+  appear to be available locally, either use ``--fetch always`` or set the
+  ``update.fetch`` :ref:`configuration option <west-config>` to ``"always"``.
 
   For safety, ``west update`` uses ``git checkout --detach`` to check out a
   detached ``HEAD`` at the manifest revision for each updated project, leaving

doc/guides/west/west-apis.rst

@@ -41,14 +41,14 @@ provided.
 
    .. automethod:: __init__
 
-   .. versionadded:: 0.6
+   .. versionadded:: 0.6.0
       The *requires_installation* parameter.
 
    Methods:
 
    .. automethod:: run
 
-   .. versionchanged:: 0.6
+   .. versionchanged:: 0.6.0
       The *topdir* argument was added.
 
    .. automethod:: add_parser
@@ -86,6 +86,16 @@ provided.
 
       The argument parser created by calling ``WestCommand.add_parser()``.
 
+   Instance properties:
+
+   .. py:attribute:: manifest
+
+      A read-only property which returns the :py:class:`west.manifest.Manifest`
+      instance for the current manifest file or aborts the program if one was
+      not provided. This is only safe to use from the ``do_run()`` method.
+
+   .. versionadded:: 0.6.1
+
 .. autoclass:: west.commands.CommandError
    :show-inheritance:
 
@@ -119,7 +129,7 @@ west.configuration
 
 .. autofunction:: west.configuration.read_config
 
-.. versionchanged:: 0.6
+.. versionchanged:: 0.6.0
    Errors due to an inability to find a local configuration file are ignored.
 
 .. autofunction:: west.configuration.update_config
@@ -136,7 +146,7 @@ west.log
 ********
 
 .. automodule:: west.log
-   :members: set_verbosity, VERBOSE_NONE, VERBOSE_NORMAL, VERBOSE_VERY, VERBOSE_EXTREME, dbg, inf, wrn, err, die
+   :members: set_verbosity, VERBOSE_NONE, VERBOSE_NORMAL, VERBOSE_VERY, VERBOSE_EXTREME, dbg, inf, wrn, err, die, banner, small_banner
 
 .. _west-apis-manifest:
 
@@ -163,6 +173,10 @@ west.manifest
 
    .. automethod:: get_remote
 
+   .. automethod:: get_projects
+
+   .. versionadded:: 0.6.1
+
    .. automethod:: as_frozen_dict
 
 .. autoclass:: west.manifest.Defaults
@@ -174,14 +188,35 @@ west.manifest
    :member-order: groupwise
 
 .. autoclass:: west.manifest.Project
-   :members:
-   :member-order: groupwise
+
+   .. automethod:: __init__
+
+   .. automethod:: as_dict
+
+   .. automethod:: format
+
+   .. automethod:: git
+
+   .. versionchanged:: 0.6.1
+      The ``capture_stderr`` kwarg.
+
+   .. automethod:: sha
+
+   .. automethod:: is_ancestor_of
+
+   .. automethod:: is_cloned
+
+   .. versionadded:: 0.6.1
+
+   .. automethod:: is_up_to_date_with
+
+   .. automethod:: is_up_to_date
 
 .. autoclass:: west.manifest.ManifestProject
    :members:
    :member-order: groupwise
 
-.. versionadded:: 0.6
+.. versionadded:: 0.6.0
 
 .. autoclass:: west.manifest.MalformedManifest
    :show-inheritance: