Re: [docs] [PATCH v3 3/5] ref-manual: improve "devtool check-upgrade-status" details

["Quentin Schulz" <foss@0leil.net>]

Hi Michael,

On September 15, 2021 7:58:40 PM GMT+02:00, Michael Opdenacker <michael.opdenacker@bootlin.com> wrote:
>- Mention "devtool latest-version recipe" to process a single version
>- Explain that the mechanism is controlled by the UPSTREAM_CHECK*
>  variables, which are not referred to anywhere else in the manuals,
>  except in the variable index.
>
>Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
>---
> .../ref-manual/devtool-reference.rst          | 29 +++++++++++++------
> documentation/ref-manual/variables.rst        |  4 +--
> 2 files changed, 22 insertions(+), 11 deletions(-)
>
>diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst
>index 5fd51569a3..2cf9fd43a3 100644
>--- a/documentation/ref-manual/devtool-reference.rst
>+++ b/documentation/ref-manual/devtool-reference.rst
>@@ -328,12 +328,19 @@ Checking on the Upgrade Status of a Recipe
> Upstream recipes change over time. Consequently, you might find that you
> need to determine if you can upgrade a recipe to a newer version.
> 
>-To check on the upgrade status of a recipe, use the
>-``devtool check-upgrade-status`` command. The command displays a table
>-of your current recipe versions, the latest upstream versions, the email
>-address of the recipe's maintainer, and any additional information such
>-as commit hash strings and reasons you might not be able to upgrade a
>-particular recipe.
>+To check on the upgrade status of a recipe, you can use the
>+``devtool latest-version recipe`` command, which quickly shows the current
>+version and the latest version available upstream. To get such information
>+for all available recipes, use the ``devtool check-upgrade-status`` command.
>+The command displays a table of your current recipe versions, the latest
>+upstream versions, the email address of the recipe's maintainer, and any
>+additional information such as commit hash strings and reasons you might
>+not be able to upgrade a particular recipe.
>+

I am always lost with singular/plural for one thing that applies to each and every one of a number of items. I am not sure "recipe versions" is correct here. I was thinking "recipes version" would match better (one version per recipe and there are many recipes) but cannot decide 🙃

"""
Each recipe will have its current version and latest upstream version, as well as the email of the maintainer and any additional information such as the commit hash or reason for not being able to upgrade it, displayed in a table.
"""

is what I could come up with. Hopefully it's a bit clearer to not only me :)


>+This upgrade checking mechanism relies on the optional :term:`UPSTREAM_CHECK_URI`,
>+:term:`UPSTREAM_CHECK_REGEX`, :term:`UPSTREAM_CHECK_GITTAGREGEX`,
>+:term:`UPSTREAM_CHECK_COMMITS` and :term:`UPSTREAM_VERSION_UNKNOWN`
>+variables which are defined in package recipes.
> 
> .. note::
> 
>@@ -342,9 +349,10 @@ particular recipe.
>       file.
> 
>    -  If the recipe is using the :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-fetching:git fetcher (\`\`git://\`\`)`
>-      rather than a
>-      tarball, the commit hash points to the commit that matches the
>-      recipe's latest version tag.
>+      rather than a tarball, the commit hash points to the commit that matches
>+      the recipe's latest version tag, or in the absence of suitable tags,
>+      to the latest commit (when :term:`UPSTREAM_CHECK_COMMITS` set to ``1``
>+      in the recipe).
> 
> As with all ``devtool`` commands, you can get help on the individual
> command::
>@@ -393,6 +401,9 @@ satisfied.
>    NOTE: busybox 1.29.2 1.30.0 Andrej Valek <andrej.valek@siemens.com>
>    NOTE: dbus-test 1.12.10 1.12.12 Chen Qi <Qi.Chen@windriver.com>
> 
>+Last but not least, you may set :term:`UPSTREAM_VERSION_UNKNOWN` to ``1``
>+in a recipe when no way is found to determine its latest upstream version.
>+

"""
when there's currently no way to determine...
"""
?
> .. _devtool-upgrading-a-recipe:
> 
> Upgrading a Recipe
>diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
>index 2342846dc7..7545e708c6 100644
>--- a/documentation/ref-manual/variables.rst
>+++ b/documentation/ref-manual/variables.rst
>@@ -8534,9 +8534,9 @@ system and gives an overview of their function and contents.
>       You can perform a per-recipe check for what the latest upstream
>       source code version is by calling ``devtool latest-version recipe``.
>       If no combination of the :term:`UPSTREAM_CHECK_URI`, :term:`UPSTREAM_CHECK_REGEX`,
>-      `UPSTREAM_CHECK_GITTAGREGEX` and :term:`UPSTREAM_CHECK_COMMITS` variables in
>+      :term:`UPSTREAM_CHECK_GITTAGREGEX` and :term:`UPSTREAM_CHECK_COMMITS` variables in
>       the recipe allows to determine such an latest upstream version,
>-      you can set :term:`UPSTREAM_VERSION_UNKNOWN`` to ``1`` in the recipe
>+      you can set :term:`UPSTREAM_VERSION_UNKNOWN` to ``1`` in the recipe

This one typo fix should be in the commit that introduces it :)

Cheers,
Quentin

>       to acknowledge that the check cannot be performed.
>       ::
>