From bd4b24810a06e7ed4de5181a1f07f550114d2f76 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 28 Aug 2019 14:07:38 -0600 Subject: [PATCH] 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 --- doc/guides/west/config.rst | 7 +++++ doc/guides/west/release-notes.rst | 43 ++++++++++++++++++++++++++- doc/guides/west/repo-tool.rst | 26 ++++++++++++---- doc/guides/west/west-apis.rst | 49 ++++++++++++++++++++++++++----- 4 files changed, 112 insertions(+), 13 deletions(-) diff --git a/doc/guides/west/config.rst b/doc/guides/west/config.rst index 67c3758d6e3..9b87b0a03ec 100644 --- a/doc/guides/west/config.rst +++ b/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 ` 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 diff --git a/doc/guides/west/release-notes.rst b/doc/guides/west/release-notes.rst index cb4ebc7ec1b..78badca2340 100644 --- a/doc/guides/west/release-notes.rst +++ b/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 ` command has a new ``--fetch`` + command line flag and ``update.fetch`` :ref:`configuration option + `. 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 ` command also handles errors + better. +- The :ref:`west list ` 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 diff --git a/doc/guides/west/repo-tool.rst b/doc/guides/west/repo-tool.rst index 42dfd3b0941..c5cbe93a0d4 100644 --- a/doc/guides/west/repo-tool.rst +++ b/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 ` 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 ` 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 diff --git a/doc/guides/west/west-apis.rst b/doc/guides/west/west-apis.rst index 070f9892d38..b474edfab90 100644 --- a/doc/guides/west/west-apis.rst +++ b/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: