[PATCH 1/4] ref-manual: remove checkpkg task

[PATCH 1/4] ref-manual: remove checkpkg task

[Michael Opdenacker]

It doesn't exist any more and its functionality is now taken care
of by "devtool check-upgrade-status"

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/ref-manual/tasks.rst     | 31 --------------------------
 documentation/ref-manual/variables.rst |  4 ++--
 2 files changed, 2 insertions(+), 33 deletions(-)

diff --git a/documentation/ref-manual/tasks.rst b/documentation/ref-manual/tasks.rst
index ecc701856c..4edae33392 100644
--- a/documentation/ref-manual/tasks.rst
+++ b/documentation/ref-manual/tasks.rst
@@ -438,37 +438,6 @@ Manually Called Tasks
 These tasks are typically manually triggered (e.g. by using the
 ``bitbake -c`` command-line option):
 
-.. _ref-tasks-checkpkg:
-
-``do_checkpkg``
----------------
-
-Provides information about the recipe including its upstream version and
-status. The upstream version and status reveals whether or not a version
-of the recipe exists upstream and a status of not updated, updated, or
-unknown.
-
-To check the upstream version and status of a recipe, use the following
-devtool commands::
-
-   $ devtool latest-version
-   $ devtool check-upgrade-status
-
-See the ":ref:`ref-manual/devtool-reference:\`\`devtool\`\` quick reference`"
-chapter for more information on
-``devtool``. See the ":ref:`devtool-checking-on-the-upgrade-status-of-a-recipe`"
-section for information on checking the upgrade status of a recipe.
-
-To build the ``checkpkg`` task, use the ``bitbake`` command with the
-"-c" option and task name::
-
-   $ bitbake core-image-minimal -c checkpkg
-
-By default, the results are stored in :term:`$LOG_DIR <LOG_DIR>` (e.g.
-``$BUILD_DIR/tmp/log``).
-
-.. _ref-tasks-checkuri:
-
 ``do_checkuri``
 ---------------
 
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 5caada6260..74d04dfd49 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -8485,7 +8485,7 @@ system and gives an overview of their function and contents.
 
    :term:`UPSTREAM_CHECK_GITTAGREGEX`
       You can perform a per-recipe check for what the latest upstream
-      source code version is by calling ``bitbake -c checkpkg`` recipe. If
+      source code version is by calling ``devtool latest-version recipe``. If
       the recipe source code is provided from Git repositories, the
       OpenEmbedded build system determines the latest upstream version by
       picking the latest tag from the list of all repository tags.
@@ -8508,7 +8508,7 @@ system and gives an overview of their function and contents.
 
    :term:`UPSTREAM_CHECK_URI`
       You can perform a per-recipe check for what the latest upstream
-      source code version is by calling ``bitbake -c checkpkg`` recipe. If
+      source code version is by calling ``devtool latest-version recipe``. If
       the source code is provided from tarballs, the latest version is
       determined by fetching the directory listing where the tarball is and
       attempting to find a later tarball. When this approach does not work,
-- 
2.25.1

[PATCH 2/4] ref-manual: improve "devtool check-upgrade-status" details

[Michael Opdenacker]

- 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>
---
 documentation/ref-manual/devtool-reference.rst | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst
index 5fd51569a3..5a0d6c25ae 100644
--- a/documentation/ref-manual/devtool-reference.rst
+++ b/documentation/ref-manual/devtool-reference.rst
@@ -328,12 +328,18 @@ 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 :term:`UPSTREAM_CHECK_URI`,
+:term:`UPSTREAM_CHECK_REGEX` and :term:`UPSTREAM_CHECK_GITTAGREGEX` variables
+which can be defined in each recipe.
 
 .. note::
 
-- 
2.25.1

[PATCH 3/4] ref-manual: improve documentation for RECIPE_NO_UPDATE_REASON

[Michael Opdenacker]

This add a description of this variable to the variable index,
and clarifies the explanations given in the devtool reference
section.

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/ref-manual/devtool-reference.rst | 13 ++++---------
 documentation/ref-manual/variables.rst         |  7 +++++++
 2 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst
index 5a0d6c25ae..761c7cb738 100644
--- a/documentation/ref-manual/devtool-reference.rst
+++ b/documentation/ref-manual/devtool-reference.rst
@@ -375,15 +375,10 @@ Following is a partial example table that reports on all the recipes.
 Notice the reported reason for not upgrading the ``base-passwd`` recipe.
 In this example, while a new version is available upstream, you do not
 want to use it because the dependency on ``cdebconf`` is not easily
-satisfied.
-
-.. note::
-
-   When a reason for not upgrading displays, the reason is usually
-   written into the recipe using the ``RECIPE_NO_UPDATE_REASON``
-   variable. See the
-   :yocto_git:`base-passwd.bb </poky/tree/meta/recipes-core/base-passwd/base-passwd_3.5.29.bb>`
-   recipe for an example.
+satisfied. Maintainers can explicit the reason that is shown by adding
+the :term:`RECIPE_NO_UPDATE_REASON` variable to the corresponding recipe.
+See :yocto_git:`base-passwd.bb </poky/tree/meta/recipes-core/base-passwd/base-passwd_3.5.29.bb>`
+for an example.
 
 ::
 
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 74d04dfd49..ecad6acfff 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -6132,6 +6132,13 @@ system and gives an overview of their function and contents.
       BitBake User Manual for additional information on tasks and
       dependencies.
 
+   :term:`RECIPE_NO_UPDATE_REASON`
+      If a recipe should not be replaced by a more recent upstream version,
+      setting this variable in a recipe allows to explain the reason why in
+      the output of the ``devtool check-upgrade-status`` command, as explained
+      in the ":ref:`ref-manual/devtool-reference:checking on the upgrade Status of a recipe`"
+      section.
+
    :term:`REQUIRED_DISTRO_FEATURES`
       When inheriting the
       :ref:`features_check <ref-classes-features_check>`
-- 
2.25.1

[PATCH 4/4] ref-manual: update "devtool check-upgrade-status" output

[Michael Opdenacker]

This command now uses "INFO" insted of "NOTES" and output
information in columns. Also good to show more recent
versions of recipes.

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/ref-manual/devtool-reference.rst | 15 ++++++---------
 1 file changed, 6 insertions(+), 9 deletions(-)

diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst
index 761c7cb738..17b62d4048 100644
--- a/documentation/ref-manual/devtool-reference.rst
+++ b/documentation/ref-manual/devtool-reference.rst
@@ -384,15 +384,12 @@ for an example.
 
    $ devtool check-upgrade-status
    ...
-   NOTE: acpid 2.0.30 2.0.31 Ross Burton <ross.burton@intel.com>
-   NOTE: u-boot-fw-utils 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff
-   NOTE: u-boot-tools 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff
-   .
-   .
-   .
-   NOTE: base-passwd 3.5.29 3.5.45 Anuj Mittal <anuj.mittal@intel.com> cannot be updated due to: Version 3.5.38 requires cdebconf for update-passwd utility
-   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>
+   INFO: bind                      9.16.20         9.16.21         Armin Kuster <akuster808@gmail.com>
+   INFO: inetutils                 2.1             2.2             Tom Rini <trini@konsulko.com>
+   INFO: iproute2                  5.13.0          5.14.0          Changhyeok Bae <changhyeok.bae@gmail.com>
+   INFO: openssl                   1.1.1l          3.0.0           Alexander Kanavin <alex.kanavin@gmail.com>
+   INFO: base-passwd               3.5.29          3.5.51          Anuj Mittal <anuj.mittal@intel.com>  cannot be updated due to: Version 3.5.38 requires cdebconf for update-passwd utility
+   ...
 
 .. _devtool-upgrading-a-recipe:
 
-- 
2.25.1

Re: [docs] [PATCH 1/4] ref-manual: remove checkpkg task

[Quentin Schulz]

Hi Michael,

On Wed, Sep 15, 2021 at 12:12:16PM +0200, Michael Opdenacker wrote:
> It doesn't exist any more and its functionality is now taken care
> of by "devtool check-upgrade-status"
> 
> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>

Reviewed-by: Quentin Schulz <foss@0leil.net>

Thanks!
Quentin

Re: [docs] [PATCH 2/4] ref-manual: improve "devtool check-upgrade-status" details

[Quentin Schulz]

Hi Michael,

On Wed, Sep 15, 2021 at 12:12:17PM +0200, Michael Opdenacker 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>
> ---
>  documentation/ref-manual/devtool-reference.rst | 18 ++++++++++++------
>  1 file changed, 12 insertions(+), 6 deletions(-)
> 
> diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst
> index 5fd51569a3..5a0d6c25ae 100644
> --- a/documentation/ref-manual/devtool-reference.rst
> +++ b/documentation/ref-manual/devtool-reference.rst
> @@ -328,12 +328,18 @@ 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.

Spurious space before `use` here.

> +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 :term:`UPSTREAM_CHECK_URI`,
> +:term:`UPSTREAM_CHECK_REGEX` and :term:`UPSTREAM_CHECK_GITTAGREGEX` variables
> +which can be defined in each recipe.
>  

I think the "can be defined in each recipe" might generate confusion and
tell people it can be defined elsewhere.

What about:

"""
This upgrade checking mechanism relies on the optional[...] variables
which are defined in package recipes.
"""

What do you think?

Cheers,
Quentin

Re: [docs] [PATCH 3/4] ref-manual: improve documentation for RECIPE_NO_UPDATE_REASON

[Quentin Schulz]

Hi Michael,

On Wed, Sep 15, 2021 at 12:12:18PM +0200, Michael Opdenacker wrote:
> This add a description of this variable to the variable index,
> and clarifies the explanations given in the devtool reference
> section.
> 
> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
> ---
>  documentation/ref-manual/devtool-reference.rst | 13 ++++---------
>  documentation/ref-manual/variables.rst         |  7 +++++++
>  2 files changed, 11 insertions(+), 9 deletions(-)
> 
> diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst
> index 5a0d6c25ae..761c7cb738 100644
> --- a/documentation/ref-manual/devtool-reference.rst
> +++ b/documentation/ref-manual/devtool-reference.rst
> @@ -375,15 +375,10 @@ Following is a partial example table that reports on all the recipes.
>  Notice the reported reason for not upgrading the ``base-passwd`` recipe.
>  In this example, while a new version is available upstream, you do not
>  want to use it because the dependency on ``cdebconf`` is not easily
> -satisfied.
> -
> -.. note::
> -
> -   When a reason for not upgrading displays, the reason is usually
> -   written into the recipe using the ``RECIPE_NO_UPDATE_REASON``
> -   variable. See the
> -   :yocto_git:`base-passwd.bb </poky/tree/meta/recipes-core/base-passwd/base-passwd_3.5.29.bb>`
> -   recipe for an example.
> +satisfied. Maintainers can explicit the reason that is shown by adding
> +the :term:`RECIPE_NO_UPDATE_REASON` variable to the corresponding recipe.
> +See :yocto_git:`base-passwd.bb </poky/tree/meta/recipes-core/base-passwd/base-passwd_3.5.29.bb>`
> +for an example.
>  
>  ::
>  
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 74d04dfd49..ecad6acfff 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -6132,6 +6132,13 @@ system and gives an overview of their function and contents.
>        BitBake User Manual for additional information on tasks and
>        dependencies.
>  
> +   :term:`RECIPE_NO_UPDATE_REASON`
> +      If a recipe should not be replaced by a more recent upstream version,
> +      setting this variable in a recipe allows to explain the reason why in

I think it's missing the information about what this variable should be
set to (the reason - a string).

What about:
"""
If a recipe should not be replaced by a more recent upstream version,
putting the reason why in this variable in a recipe allows
``devtool check-upgrade-status`` command to display it, as explained
[...]
"""

What do you think?

> +      the output of the ``devtool check-upgrade-status`` command, as explained
> +      in the ":ref:`ref-manual/devtool-reference:checking on the upgrade Status of a recipe`"

lowercase S in the reflink?

Cheers,
Quentin

Re: [docs] [PATCH 3/4] ref-manual: improve documentation for RECIPE_NO_UPDATE_REASON

[Michael Opdenacker]

Hi Quentin,

Many thanks for the reviews!

On 9/15/21 1:54 PM, Quentin Schulz wrote:
>
>>  
>> +   :term:`RECIPE_NO_UPDATE_REASON`
>> +      If a recipe should not be replaced by a more recent upstream version,
>> +      setting this variable in a recipe allows to explain the reason why in
> I think it's missing the information about what this variable should be
> set to (the reason - a string).
>
> What about:
> """
> If a recipe should not be replaced by a more recent upstream version,
> putting the reason why in this variable in a recipe allows
> ``devtool check-upgrade-status`` command to display it, as explained
> [...]
> """
>
> What do you think?


That's definitely clearer. Adopted, thanks!

>
>> +      the output of the ``devtool check-upgrade-status`` command, as explained
>> +      in the ":ref:`ref-manual/devtool-reference:checking on the upgrade Status of a recipe`"
> lowercase S in the reflink?


Oops, forgot that one, thanks!

Cheers,
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] [PATCH 2/4] ref-manual: improve "devtool check-upgrade-status" details

[Michael Opdenacker]

Hello Quentin,

Thanks again for the reviews.

On 9/15/21 1:44 PM, Quentin Schulz wrote:
>
>> +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.
> Spurious space before `use` here.

Good catch, fixed, thanks.

>
>> +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 :term:`UPSTREAM_CHECK_URI`,
>> +:term:`UPSTREAM_CHECK_REGEX` and :term:`UPSTREAM_CHECK_GITTAGREGEX` variables
>> +which can be defined in each recipe.
>>  
> I think the "can be defined in each recipe" might generate confusion and
> tell people it can be defined elsewhere.
>
> What about:
>
> """
> This upgrade checking mechanism relies on the optional[...] variables
> which are defined in package recipes.
> """
>
> What do you think?

Great. I wasn't really happy with the way I wrote it, and this is just
right! Adopted.
Many thanks,
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com