The functionality overlaps somewhat. 'devtool latest-version' takes a single recipe as an argument, but 'devtool check-upgrade-status' takes a list of recipes, or nothing (in which case a check for everything runs), and prints only the items where there is a new upstream version available in a table format. The former is intended when you want to see a specific status of something particular, the latter for an overall picture.

Alex

On Wed, 15 Sept 2021 at 19:58, 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.
+
+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.
+
 .. _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
       to acknowledge that the check cannot be performed.
       ::

--
2.25.1