[PATCH 00/13] Documentation updates for 3.3

[PATCH 00/13] Documentation updates for 3.3

[Paul Eggleton]

The migration guide for 3.3, plus some missing related changes and a few
cleanups. Let me know if I missed anything.


The following changes since commit 4f7f451df266a307b34bf145b29291ca85eb882f:

  docs: add a top level page for bitbake documentation (2021-04-09 09:00:53 +0200)

are available in the git repository at:

  git://git.yoctoproject.org/poky-contrib paule/migration-3.3
  http://git.yoctoproject.org/cgit.cgi/poky-contrib/log/?h=paule/migration-3.3

Paul Eggleton (13):
  ref-manual: add METADATA_REVISION and METADATA_BRANCH
  Use variables for minimum host versions and bump Python to 3.6
  ref-manual: update/fix text for SDK_VERSION
  overview-manual: fix git command line
  ref-manual: and SDK_CUSTOM_TEMPLATECONF to glossary
  ref-manual: add REQUIRED_VERSION and adjust PREFERRED_VERSION entry
  ref-manual: add python3targetconfig class and remove python 2 references
  ref-manual: add passwd-expire to EXTRA_USERS_PARAMS
  ref-manual: add FIT_KERNEL_COMP_ALG*
  ref-manual: fix reference to build-essential
  ref-manual: tweak buildtools section
  ref-manual: add migration section for 3.3 release
  ref-manual: migration guide: add release codenames

 documentation/brief-yoctoprojectqs/index.rst       |   8 +-
 documentation/dev-manual/start.rst                 |   8 +-
 .../overview-manual/development-environment.rst    |   2 +-
 documentation/poky.yaml                            |   4 +
 documentation/ref-manual/classes.rst               |  67 +++-------
 documentation/ref-manual/faq.rst                   |   2 +-
 documentation/ref-manual/migration-1.3.rst         |   6 +-
 documentation/ref-manual/migration-1.4.rst         |   6 +-
 documentation/ref-manual/migration-1.5.rst         |   6 +-
 documentation/ref-manual/migration-1.6.rst         |   6 +-
 documentation/ref-manual/migration-1.7.rst         |   6 +-
 documentation/ref-manual/migration-1.8.rst         |   6 +-
 documentation/ref-manual/migration-2.0.rst         |   6 +-
 documentation/ref-manual/migration-2.1.rst         |   6 +-
 documentation/ref-manual/migration-2.2.rst         |   6 +-
 documentation/ref-manual/migration-2.3.rst         |   6 +-
 documentation/ref-manual/migration-2.4.rst         |   6 +-
 documentation/ref-manual/migration-2.5.rst         |   6 +-
 documentation/ref-manual/migration-2.6.rst         |   8 +-
 documentation/ref-manual/migration-2.7.rst         |   6 +-
 documentation/ref-manual/migration-3.0.rst         |   6 +-
 documentation/ref-manual/migration-3.1.rst         |   6 +-
 documentation/ref-manual/migration-3.2.rst         |   6 +-
 documentation/ref-manual/migration-3.3.rst         | 144 +++++++++++++++++++++
 documentation/ref-manual/migration.rst             |   1 +
 documentation/ref-manual/system-requirements.rst   |  19 ++-
 documentation/ref-manual/variables.rst             |  75 ++++++++---
 27 files changed, 299 insertions(+), 135 deletions(-)
 create mode 100644 documentation/ref-manual/migration-3.3.rst

-- 
1.8.3.1

[PATCH 01/13] ref-manual: add METADATA_REVISION and METADATA_BRANCH

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

These are not new variables, but we are using METADATA_REVISION in a new
place and thus need to refer to it.

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/ref-manual/variables.rst | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 19f5e34..de63046 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -4659,6 +4659,14 @@ system and gives an overview of their function and contents.
    :term:`MAINTAINER`
       The email address of the distribution maintainer.
 
+   :term:`METADATA_BRANCH`
+      The branch currently checked out for the core layer (path determined by
+      :term:`COREBASE`).
+
+   :term:`METADATA_REVISION`
+      The revision currently checked out for the core layer (path determined by
+      :term:`COREBASE`).
+
    :term:`MIRRORS`
       Specifies additional paths from which the OpenEmbedded build system
       gets source code. When the build system searches for source code, it
-- 
1.8.3.1

[PATCH 02/13] Use variables for minimum host versions and bump Python to 3.6

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

Minimum Git, tar, Python and gcc versions are specified in quite a few
different places. Let's add some variables for these so there's no
chance of missing one if they're updated in future. Additionally, for
hardknott the minimum Python version is 3.6 so set that as the value for
Python.

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/brief-yoctoprojectqs/index.rst     | 8 ++++----
 documentation/dev-manual/start.rst               | 8 ++++----
 documentation/poky.yaml                          | 4 ++++
 documentation/ref-manual/faq.rst                 | 2 +-
 documentation/ref-manual/system-requirements.rst | 8 ++++----
 5 files changed, 17 insertions(+), 13 deletions(-)

diff --git a/documentation/brief-yoctoprojectqs/index.rst b/documentation/brief-yoctoprojectqs/index.rst
index 7bba47e..974ae5e 100644
--- a/documentation/brief-yoctoprojectqs/index.rst
+++ b/documentation/brief-yoctoprojectqs/index.rst
@@ -60,10 +60,10 @@ following requirements:
 
 -
 
-   -  Git 1.8.3.1 or greater
-   -  tar 1.28 or greater
-   -  Python 3.5.0 or greater.
-   -  gcc 5.0 or greater.
+   -  Git &MIN_GIT_VERSION; or greater
+   -  tar &MIN_TAR_VERSION; or greater
+   -  Python &MIN_PYTHON_VERSION; or greater.
+   -  gcc &MIN_GCC_VERSION; or greater.
 
 If your build host does not meet any of these three listed version
 requirements, you can take steps to prepare the system so that you
diff --git a/documentation/dev-manual/start.rst b/documentation/dev-manual/start.rst
index 3903618..84abf4c 100644
--- a/documentation/dev-manual/start.rst
+++ b/documentation/dev-manual/start.rst
@@ -314,13 +314,13 @@ Project Build Host:
    should be able to run on any modern distribution that has the
    following versions for Git, tar, Python and gcc.
 
-   -  Git 1.8.3.1 or greater
+   -  Git &MIN_GIT_VERSION; or greater
 
-   -  tar 1.28 or greater
+   -  tar &MIN_TAR_VERSION; or greater
 
-   -  Python 3.5.0 or greater.
+   -  Python &MIN_PYTHON_VERSION; or greater.
 
-   -  gcc 5.0 or greater.
+   -  gcc &MIN_GCC_VERSION; or greater.
 
    If your build host does not meet any of these three listed version
    requirements, you can take steps to prepare the system so that you
diff --git a/documentation/poky.yaml b/documentation/poky.yaml
index e0cf0b3..8ccb359 100644
--- a/documentation/poky.yaml
+++ b/documentation/poky.yaml
@@ -40,3 +40,7 @@ CENTOS8_HOST_PACKAGES_ESSENTIAL : "-y epel-release
      python3-GitPython python3-jinja2 python3-pexpect xz which SDL-devel xterm \
      rpcgen mesa-libGL-devel"
 PIP3_HOST_PACKAGES_DOC : "$ sudo pip3 install sphinx sphinx_rtd_theme pyyaml"
+MIN_PYTHON_VERSION : "3.6.0"
+MIN_TAR_VERSION : "1.28"
+MIN_GIT_VERSION : "1.8.3.1"
+MIN_GCC_VERSION : "5.0"
diff --git a/documentation/ref-manual/faq.rst b/documentation/ref-manual/faq.rst
index 3b65588..64fdfdf 100644
--- a/documentation/ref-manual/faq.rst
+++ b/documentation/ref-manual/faq.rst
@@ -16,7 +16,7 @@ first before being pulled back into Poky. This practice benefits both
 projects immediately.
 
 **Q:** My development system does not meet the required Git, tar, and
-Python versions. In particular, I do not have Python 3.5.0 or greater.
+Python versions. In particular, I do not have Python &MIN_PYTHON_VERSION; or greater.
 Can I still use the Yocto Project?
 
 **A:** You can get the required tools on your host development system a
diff --git a/documentation/ref-manual/system-requirements.rst b/documentation/ref-manual/system-requirements.rst
index 6edfa1a..dc619ce 100644
--- a/documentation/ref-manual/system-requirements.rst
+++ b/documentation/ref-manual/system-requirements.rst
@@ -256,11 +256,11 @@ Required Git, tar, Python and gcc Versions
 In order to use the build system, your host development system must meet
 the following version requirements for Git, tar, and Python:
 
--  Git 1.8.3.1 or greater
+-  Git &MIN_GIT_VERSION; or greater
 
--  tar 1.28 or greater
+-  tar &MIN_TAR_VERSION; or greater
 
--  Python 3.5.0 or greater
+-  Python &MIN_PYTHON_VERSION; or greater
 
 If your host development system does not meet all these requirements,
 you can resolve this by installing a ``buildtools`` tarball that
@@ -270,7 +270,7 @@ a pre-built tarball or use BitBake to build the tarball.
 In addition, your host development system must meet the following
 version requirement for gcc:
 
--  gcc 5.0 or greater
+-  gcc &MIN_GCC_VERSION; or greater
 
 If your host development system does not meet this requirement, you can
 resolve this by installing a ``buildtools-extended`` tarball that
-- 
1.8.3.1

[PATCH 03/13] ref-manual: update/fix text for SDK_VERSION

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

DISTRO_VERSION snapshot versions use METADATA_REVISION not DATE in
hardknott and thus the default for SDK_VERSION has been updated, so
update it here as well. Additionally, fix the text so it makes sense.

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/ref-manual/variables.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index de63046..b9478a3 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -6764,16 +6764,16 @@ system and gives an overview of their function and contents.
       Specifies the name of the SDK vendor.
 
    :term:`SDK_VERSION`
-      Specifies the version of the SDK. The distribution configuration file
-      (e.g. ``/meta-poky/conf/distro/poky.conf``) defines the
+      Specifies the version of the SDK. The Poky distribution configuration file
+      (``/meta-poky/conf/distro/poky.conf``) sets the default
       ``SDK_VERSION`` as follows:
       ::
 
-         SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${DATE}','snapshot')}"
+         SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${METADATA_REVISION}', 'snapshot')}"
 
       For additional information, see the
       :term:`DISTRO_VERSION` and
-      :term:`DATE` variables.
+      :term:`METADATA_REVISION` variables.
 
    :term:`SDKEXTPATH`
       The default installation directory for the Extensible SDK. By
-- 
1.8.3.1

[PATCH 04/13] overview-manual: fix git command line

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

There was an en dash here instead of a hyphen; this meant that the
command line could not be copied and pasted verbatim. (Admittedly that
is less likely here than in other examples, but let's correct it
anyway.)

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/overview-manual/development-environment.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/overview-manual/development-environment.rst b/documentation/overview-manual/development-environment.rst
index 6d1dbfc..a33f89e 100644
--- a/documentation/overview-manual/development-environment.rst
+++ b/documentation/overview-manual/development-environment.rst
@@ -542,7 +542,7 @@ descriptions and strategies on how to use these commands:
    in this form assumes the local branch already exists. This command is
    analogous to "cd".
 
--  *git checkout –b working-branch upstream-branch:* Creates and
+-  *git checkout -b working-branch upstream-branch:* Creates and
    checks out a working branch on your local machine. The local branch
    tracks the upstream branch. You can use your local branch to isolate
    your work. It is a good idea to use local branches when adding
-- 
1.8.3.1

[PATCH 05/13] ref-manual: and SDK_CUSTOM_TEMPLATECONF to glossary

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/ref-manual/variables.rst | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index b9478a3..ef61339 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -6489,6 +6489,11 @@ system and gives an overview of their function and contents.
       The target architecture for the SDK. Typically, you do not directly
       set this variable. Instead, use :term:`SDKMACHINE`.
 
+   :term:`SDK_CUSTOM_TEMPLATECONF`
+      When building the extensible SDK, if ``SDK_CUSTOM_TEMPLATECONF`` is set to
+      "1" and a ``conf/templateconf.conf`` file exists in the build directory
+      (``TOPDIR``) then this will be copied into the SDK.
+
    :term:`SDK_DEPLOY`
       The directory set up and used by the
       :ref:`populate_sdk_base <ref-classes-populate-sdk>` class to which
-- 
1.8.3.1

[PATCH 06/13] ref-manual: add REQUIRED_VERSION and adjust PREFERRED_VERSION entry

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

Add REQUIRED_VERSION, add a reference to it in PREFERRED_VERSION and
adjust the opening statement to read slightly better.

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/ref-manual/variables.rst | 22 ++++++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index ef61339..a97f858 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -5798,10 +5798,10 @@ system and gives an overview of their function and contents.
          exclusive alternative providers.
 
    :term:`PREFERRED_VERSION`
-      If multiple versions of recipes exist, this variable determines which
-      version is given preference. You must always suffix the variable with
-      the :term:`PN` you want to select, and you should set the
-      :term:`PV` accordingly for precedence.
+      If there are multiple versions of a recipe available, this variable
+      determines which version should be given preference. You must always
+      suffix the variable with the :term:`PN` you want to select, and you
+      should set the :term:`PV` accordingly for precedence.
 
       The ``PREFERRED_VERSION`` variable supports limited wildcard use
       through the "``%``" character. You can use the character to match any
@@ -5859,6 +5859,10 @@ system and gives an overview of their function and contents.
          The ``\_forcevariable`` override is not handled specially. This override
          only works because the default value of ``OVERRIDES`` includes "forcevariable".
 
+      If a recipe with the specified version is not available, a warning
+      message will be shown. See :term:`REQUIRED_VERSION` if you want this
+      to be an error instead.
+
    :term:`PREMIRRORS`
       Specifies additional paths from which the OpenEmbedded build system
       gets source code. When the build system searches for source code, it
@@ -6216,6 +6220,16 @@ system and gives an overview of their function and contents.
       the recipe will be skipped, and if the build system attempts to build
       the recipe then an error will be triggered.
 
+   :term:`REQUIRED_VERSION`
+      If there are multiple versions of a recipe available, this variable
+      determines which version should be given preference. ``REQUIRED_VERSION``
+      works in exactly the same manner as :term:`PREFERRED_VERSION`, except
+      that if the specified version is not available then an error message
+      is shown and the build fails immediately.
+
+      If both ``REQUIRED_VERSION`` and ``PREFERRED_VERSION`` are set for
+      the same recipe, the ``REQUIRED_VERSION`` value applies.
+
    :term:`RM_WORK_EXCLUDE`
       With ``rm_work`` enabled, this variable specifies a list of recipes
       whose work directories should not be removed. See the
-- 
1.8.3.1

[PATCH 07/13] ref-manual: add python3targetconfig class and remove python 2 references

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

Add the recently added python3targetconfig class. Also, we no longer
have the python 2 classes, remove all references to those.

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/ref-manual/classes.rst       | 67 +++++++-----------------------
 documentation/ref-manual/migration-2.6.rst |  2 +-
 documentation/ref-manual/variables.rst     | 10 ++---
 3 files changed, 20 insertions(+), 59 deletions(-)

diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index 6d9779f..52a50fa 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -501,29 +501,6 @@ Support for other version control systems such as Subversion is limited
 due to BitBake's automatic fetch dependencies (e.g.
 ``subversion-native``).
 
-.. _ref-classes-distutils:
-
-``distutils*.bbclass``
-======================
-
-The ``distutils*`` classes support recipes for Python version 2.x
-extensions, which are simple. These recipes usually only need to point
-to the source's archive and then inherit the proper class. Building is
-split into two methods depending on which method the module authors
-used.
-
--  Extensions that use an Autotools-based build system require Autotools
-   and the classes based on ``distutils`` in their recipes.
-
--  Extensions that use build systems based on ``distutils`` require the
-   ``distutils`` class in their recipes.
-
--  Extensions that use build systems based on ``setuptools`` require the
-   :ref:`setuptools <ref-classes-setuptools>` class in their recipes.
-
-The ``distutils-common-base`` class is required by some of the
-``distutils*`` classes to provide common Python2 support.
-
 .. _ref-classes-distutils3:
 
 ``distutils3*.bbclass``
@@ -542,15 +519,9 @@ used.
    ``distutils`` class in their recipes.
 
 -  Extensions that use build systems based on ``setuptools3`` require
-   the :ref:`setuptools3 <ref-classes-setuptools>` class in their
+   the :ref:`setuptools3 <ref-classes-setuptools3>` class in their
    recipes.
 
-The ``distutils3*`` classes either inherit their corresponding
-``distutils*`` class or replicate them using a Python3 version instead
-(e.g. ``distutils3-base`` inherits ``distutils-common-base``, which is
-the same as ``distutils-base`` but inherits ``python3native`` instead of
-``pythonnative``).
-
 .. _ref-classes-externalsrc:
 
 ``externalsrc.bbclass``
@@ -2138,13 +2109,13 @@ For information on setting up and running ptests, see the
 ":ref:`dev-manual/common-tasks:testing packages with ptest`"
 section in the Yocto Project Development Tasks Manual.
 
-.. _ref-classes-python-dir:
+.. _ref-classes-python3-dir:
 
-``python-dir.bbclass``
-======================
+``python3-dir.bbclass``
+=======================
 
-The ``python-dir`` class provides the base version, location, and site
-package location for Python.
+The ``python3-dir`` class provides the base version, location, and site
+package location for Python 3.
 
 .. _ref-classes-python3native:
 
@@ -2155,14 +2126,17 @@ The ``python3native`` class supports using the native version of Python
 3 built by the build system rather than support of the version provided
 by the build host.
 
-.. _ref-classes-pythonnative:
+.. _ref-classes-python3targetconfig:
 
-``pythonnative.bbclass``
-========================
+``python3targetconfig.bbclass``
+===============================
 
-When inherited by a recipe, the ``pythonnative`` class supports using
-the native version of Python built by the build system rather than using
-the version provided by the build host.
+The ``python3targetconfig`` class supports using the native version of Python
+3 built by the build system rather than support of the version provided
+by the build host, except that the configuration for the target machine
+is accessible (such as correct installation directories). This also adds a
+dependency on target ``python3``, so should only be used where appropriate
+in order to avoid unnecessarily lengthening builds.
 
 .. _ref-classes-qemu:
 
@@ -2323,22 +2297,13 @@ additional configuration options you want to pass SCons command line.
 The ``sdl`` class supports recipes that need to build software that uses
 the Simple DirectMedia Layer (SDL) library.
 
-.. _ref-classes-setuptools:
-
-``setuptools.bbclass``
-======================
-
-The ``setuptools`` class supports Python version 2.x extensions that use
-build systems based on ``setuptools``. If your recipe uses these build
-systems, the recipe needs to inherit the ``setuptools`` class.
-
 .. _ref-classes-setuptools3:
 
 ``setuptools3.bbclass``
 =======================
 
 The ``setuptools3`` class supports Python version 3.x extensions that
-use build systems based on ``setuptools3``. If your recipe uses these
+use build systems based on ``setuptools``. If your recipe uses these
 build systems, the recipe needs to inherit the ``setuptools3`` class.
 
 .. _ref-classes-sign_rpm:
diff --git a/documentation/ref-manual/migration-2.6.rst b/documentation/ref-manual/migration-2.6.rst
index 0517b0a..823d3cb 100644
--- a/documentation/ref-manual/migration-2.6.rst
+++ b/documentation/ref-manual/migration-2.6.rst
@@ -118,7 +118,7 @@ For names of recipes removed because of this repository change, see the
 ---------------------------------------------------------------------------------------------------
 
 Previously, it was possible for Python recipes that inherited the
-:ref:`distutils <ref-classes-distutils>` and
+``distutils`` and
 :ref:`distutils3 <ref-classes-distutils3>` classes to fetch code
 during the :ref:`ref-tasks-configure` task to satisfy
 dependencies mentioned in ``setup.py`` if those dependencies were not
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index a97f858..2e3cc22 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -6029,9 +6029,7 @@ system and gives an overview of their function and contents.
    :term:`PYTHON_ABI`
       When used by recipes that inherit the
       :ref:`distutils3 <ref-classes-distutils3>`,
-      :ref:`setuptools3 <ref-classes-setuptools3>`,
-      :ref:`distutils <ref-classes-distutils>`, or
-      :ref:`setuptools <ref-classes-setuptools>` classes, denotes the
+      :ref:`setuptools3 <ref-classes-setuptools3>` classes, denotes the
       Application Binary Interface (ABI) currently in use for Python. By
       default, the ABI is "m". You do not have to set this variable as the
       OpenEmbedded build system sets it for you.
@@ -6040,16 +6038,14 @@ system and gives an overview of their function and contents.
       names used when installing the Python headers and libraries in
       sysroot (e.g. ``.../python3.3m/...``).
 
-      Recipes that inherit the ``distutils`` class during cross-builds also
+      Recipes that inherit the ``distutils3`` class during cross-builds also
       use this variable to locate the headers and libraries of the
       appropriate Python that the extension is targeting.
 
    :term:`PYTHON_PN`
       When used by recipes that inherit the
       `distutils3 <ref-classes-distutils3>`,
-      :ref:`setuptools3 <ref-classes-setuptools3>`,
-      :ref:`distutils <ref-classes-distutils>`, or
-      :ref:`setuptools <ref-classes-setuptools>` classes, specifies the
+      :ref:`setuptools3 <ref-classes-setuptools3>` classes, specifies the
       major Python version being built. For Python 3.x, ``PYTHON_PN`` would
       be "python3". You do not have to set this variable as the
       OpenEmbedded build system automatically sets it for you.
-- 
1.8.3.1

[PATCH 08/13] ref-manual: add passwd-expire to EXTRA_USERS_PARAMS

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

Add a reference to the recently added passwd-expire command in
EXTRA_USERS_PARAMS.

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/ref-manual/variables.rst | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 2e3cc22..3b76dbc 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -2293,6 +2293,17 @@ system and gives an overview of their function and contents.
          # usermod -s /bin/sh tester; \
          # "
 
+      Additionally there is a special ``passwd-expire`` command that will
+      cause the password for a user to be expired and thus force changing it
+      on first login, for example: ::
+
+         EXTRA_USERS_PARAMS += " useradd myuser; passwd-expire myuser;"
+
+      .. note::
+
+         At present, ``passwd-expire`` may only work for remote logins when
+         using OpenSSH and not dropbear as an SSH server.
+
    :term:`FEATURE_PACKAGES`
       Defines one or more packages to include in an image when a specific
       item is included in :term:`IMAGE_FEATURES`.
-- 
1.8.3.1

[PATCH 09/13] ref-manual: add FIT_KERNEL_COMP_ALG*

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

Add FIT_KERNEL_COMP_ALG and FIT_KERNEL_COMP_ALG_EXTENSION. Examining
OE-Core commit 5c72105e2973e613b5c0f0e6310ffdea6e56c6c7 and the
associated code, these do not enable arbitrary selection of compression
algorithm - only disabling compression - so document them accordingly.

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/ref-manual/variables.rst | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 3b76dbc..f010cd7 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -2580,6 +2580,17 @@ system and gives an overview of their function and contents.
    :term:`FIT_HASH_ALG`
       Specifies the hash algorithm used in creating the FIT Image. For e.g. sha256.
 
+   :term:`FIT_KERNEL_COMP_ALG`
+      Compression algorithm to use for the kernel image inside the fitImage.
+      At present, the only supported values are "gzip" (default) or "none",
+      which allows disabling of compression if it would otherwise be enabled.
+      If you set this you will also need to set :term:`FIT_KERNEL_COMP_ALG_EXTENSION`.
+
+   :term:`FIT_KERNEL_COMP_ALG_EXTENSION`
+      File extension corresponding to :term:`FIT_KERNEL_COMP_ALG`. The default
+      value is ".gz"; if you set ``FIT_KERNEL_COMP_ALG`` to "none" then
+      ``FIT_KERNEL_COMP_ALG_EXTENSION`` should be set to "".
+
    :term:`FIT_KEY_GENRSA_ARGS`
       Arguments to openssl genrsa for generating RSA private key for signing
       fitImage. The default value is "-F4". i.e. the public exponent 65537 to
-- 
1.8.3.1

[PATCH 10/13] ref-manual: fix reference to build-essential

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

This has been here since the text was added to the DocBook version.

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/ref-manual/system-requirements.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/documentation/ref-manual/system-requirements.rst b/documentation/ref-manual/system-requirements.rst
index dc619ce..2e2d0d3 100644
--- a/documentation/ref-manual/system-requirements.rst
+++ b/documentation/ref-manual/system-requirements.rst
@@ -274,7 +274,8 @@ version requirement for gcc:
 
 If your host development system does not meet this requirement, you can
 resolve this by installing a ``buildtools-extended`` tarball that
-contains additional tools, the equivalent of ``buildtools-essential``.
+contains additional tools, the equivalent of the Debian/Ubuntu ``build-essential``
+package.
 
 Installing a Pre-Built ``buildtools`` Tarball with ``install-buildtools`` script
 --------------------------------------------------------------------------------
-- 
1.8.3.1

[PATCH 11/13] ref-manual: tweak buildtools section

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

Add a joining paragraph and fix the second section so that it makes
sense with the addition of the first one.

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/ref-manual/system-requirements.rst | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/documentation/ref-manual/system-requirements.rst b/documentation/ref-manual/system-requirements.rst
index 2e2d0d3..80378ce 100644
--- a/documentation/ref-manual/system-requirements.rst
+++ b/documentation/ref-manual/system-requirements.rst
@@ -277,6 +277,9 @@ resolve this by installing a ``buildtools-extended`` tarball that
 contains additional tools, the equivalent of the Debian/Ubuntu ``build-essential``
 package.
 
+In the sections that follow, three different methods will be described for
+installing the ``buildtools`` or ``buildtools-extended`` toolset.
+
 Installing a Pre-Built ``buildtools`` Tarball with ``install-buildtools`` script
 --------------------------------------------------------------------------------
 
@@ -332,8 +335,9 @@ installer and automatically installs the tools for you:
 Downloading a Pre-Built ``buildtools`` Tarball
 ----------------------------------------------
 
-Downloading and running a pre-built buildtools installer is the easiest
-of the two methods by which you can get these tools:
+If you would prefer not to use the ``install-buildtools`` script, you can instead
+download and run a pre-built buildtools installer yourself with the following
+steps:
 
 1. Locate and download the ``*.sh`` at &YOCTO_RELEASE_DL_URL;/buildtools/
 
-- 
1.8.3.1

[PATCH 12/13] ref-manual: add migration section for 3.3 release

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/ref-manual/migration-3.3.rst | 144 +++++++++++++++++++++++++++++
 documentation/ref-manual/migration.rst     |   1 +
 2 files changed, 145 insertions(+)
 create mode 100644 documentation/ref-manual/migration-3.3.rst

diff --git a/documentation/ref-manual/migration-3.3.rst b/documentation/ref-manual/migration-3.3.rst
new file mode 100644
index 0000000..8dfbe7f
--- /dev/null
+++ b/documentation/ref-manual/migration-3.3.rst
@@ -0,0 +1,144 @@
+Moving to the Yocto Project 3.3 Release
+=======================================
+
+This section provides migration information for moving to the Yocto
+Project 3.3 Release from the prior release.
+
+
+.. _migration-3.3-minimum-system-requirements:
+
+Minimum system requirements
+---------------------------
+
+You will now need at least Python 3.6 installed on your build host. Most recent
+distributions provide this, but should you be building on a distribution that
+does not have it, you can use the ``buildtools-tarball`` (easily installable
+using ``scripts/install-buildtools``) - see
+:ref:`ref-manual/system-requirements:required git, tar, python and gcc versions`
+for details.
+
+
+.. _migration-3.3-removed-recipes:
+
+Removed recipes
+---------------
+
+The following recipes have been removed:
+
+- ``go-dep``: obsolete with the advent of go modules
+- ``gst-validate``: replaced by ``gst-devtools``
+- ``linux-yocto``: removed 5.8 version recipes (5.4 / 5.10 still provided)
+- ``vulkan-demos``: replaced by ``vulkan-samples``
+
+
+.. _migration-3.3-common-license-only-versions:
+
+Single version common license file naming
+-----------------------------------------
+
+Some license files in ``meta/files/common-licenses`` have been renamed to match
+current SPDX naming conventions:
+
+- AGPL-3.0 -> AGPL-3.0-only
+- GPL-1.0 -> GPL-1.0-only
+- GPL-2.0 -> GPL-2.0-only
+- GPL-3.0 -> GPL-3.0-only
+- LGPL-2.0 -> LGPL-2.0-only
+- LGPL-2.1 -> LGPL-2.1-only
+- LGPL-3.0 -> LGPL-3.0-only
+
+Additionally, corresponding "-or-later" suffixed files have been added e.g.
+``GPL-2.0-or-later``.
+
+It is not required that you change :term:`LICENSE` values as there are mappings
+from the original names in place; however, in rare cases where you have a recipe
+which sets :term:`LIC_FILES_CHKSUM` to point to file(s) in
+``meta/files/common-licenses`` (which in any case is not recommended) you will
+need to update those.
+
+
+.. _migration-3.3-python3targetconfig:
+
+New ``python3targetconfig`` class
+---------------------------------
+
+A new :ref:`python3targetconfig <ref-classes-python3targetconfig>` class has been
+created for situations where you would previously have inherited the
+``python3native`` class but need access to target configuration data (such as
+correct installation directories). Recipes where this situation applies should
+be changed to inherit ``python3targetconfig`` instead of ``python3native``. This
+also adds a dependency on target ``python3``, so it should only be used where
+appropriate in order to avoid unnecessarily lengthening builds.
+
+Some example recipes where this change has been made: ``gpgme``, ``libcap-ng``,
+``python3-pycairo``.
+
+
+.. _migration-3.3-bitbake:
+
+BitBake changes
+---------------
+
+- BitBake is now configured to use a default ``umask`` of ``022`` for all tasks
+  (specified via a new ``BB_DEFAULT_UMASK`` variable). If needed, ``umask`` can
+  still be set on a per-task basis via the ``umask`` varflag on the task
+  function, but that is unlikely to be necessary in most cases.
+
+- If a version specified in :term:`PREFERRED_VERSION` is not available this
+  will now trigger a warning instead of just a note, making such issues more
+  visible.
+
+
+.. _migration-3.3-packaging:
+
+Packaging changes
+-----------------
+
+The following packaging changes have been made; in all cases the main package
+still depends upon the split out packages so you should not need to do anything
+unless you want to take advantage of the improved granularity:
+
+- ``dbus``: ``-common`` and ``-tools`` split out
+- ``iproute2``: split ip binary to its own package
+- ``net-tools``: split ``mii-tool`` into its own package
+- ``procps``: split ``ps`` and ``sysctl`` into their own packages
+- ``rpm``: split build and extra functionality into separate packages
+- ``sudo``: split ``sudo`` binary into ``sudo-sudo`` and libs into ``sudo-lib``
+- ``systemtap``: examples, python scripts and runtime material split out
+- ``util-linux``: ``libuuid`` has been split out to its own
+  ``util-linux-libuuid`` recipe (and corresponding packages) to avoid circular
+  dependencies if ``libgcrypt`` support is enabled in ``util-linux``.
+  (``util-linux`` depends upon ``util-linux-libuuid``.)
+
+
+.. _migration-3.3-misc:
+
+Miscellaneous changes
+---------------------
+
+- The default poky :term:`DISTRO_VERSION` value now uses the core metadata's
+  git hash (i.e. :term:`METADATA_REVISION`) rather than the date (i.e.
+  :term:`DATE`) to reduce one small source of non-reproducibility. You can
+  of course specify your own ``DISTRO_VERSION`` value as desired
+  (particularly if you create your own custom distro configuration).
+- The :ref:`ccache <ref-classes-ccache>` class now uses ``ccache`` from the
+  build host rather than building ``ccache-native`` (due to circular
+  dependencies in ccache 4.0 that are impractical to resolve otherwise), so
+  if you enable it you will now need to have ``ccache`` installed on your
+  host system.
+- ``adwaita-icon-theme`` version 3.34.3 has been added back, and is selected
+  as the default via :term:`PREFERRED_VERSION` in
+  ``meta/conf/distro/include/default-versions.inc`` due to newer versions
+  not working well with ``librsvg`` 2.40. ``librsvg`` is not practically
+  upgradeable at the moment as it has been ported to Rust, and Rust is not
+  (yet) in OE-Core, but this will change in a future release.
+- ``ffmpeg`` is now configured to disable GPL-licensed portions by default
+  to make it harder to accidentally violate the GPL. To explicitly enable GPL
+  licensed portions, add ``gpl`` to :term:`PACKAGECONFIG` for ``ffmpeg``
+  using a bbappend (or use ``PACKAGECONFIG_append_pn-ffmpeg = " gpl"`` in
+  your configuration.)
+- ``connman`` is now set to conflict with ``systemd-networkd`` as they
+  overlap functionally and may interfere with each other at runtime.
+- Canonical SPDX license names are now used in image license manifests in
+  order to avoid aliases of the same license from showing up together (e.g.
+  ``GPLv2`` and ``GPL-2.0``)
diff --git a/documentation/ref-manual/migration.rst b/documentation/ref-manual/migration.rst
index 8d64a7d..a01d4ee 100644
--- a/documentation/ref-manual/migration.rst
+++ b/documentation/ref-manual/migration.rst
@@ -28,4 +28,5 @@ notes for a given release.
    migration-3.0
    migration-3.1
    migration-3.2
+   migration-3.3
 
-- 
1.8.3.1

[PATCH 13/13] ref-manual: migration guide: add release codenames

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

People will see release codenames in other contexts, and thus it is
useful to mention them explicitly here rather than having to go to the
Releases wiki page to map version number to release codename.

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/ref-manual/migration-1.3.rst | 6 +++---
 documentation/ref-manual/migration-1.4.rst | 6 +++---
 documentation/ref-manual/migration-1.5.rst | 6 +++---
 documentation/ref-manual/migration-1.6.rst | 6 +++---
 documentation/ref-manual/migration-1.7.rst | 6 +++---
 documentation/ref-manual/migration-1.8.rst | 6 +++---
 documentation/ref-manual/migration-2.0.rst | 6 +++---
 documentation/ref-manual/migration-2.1.rst | 6 +++---
 documentation/ref-manual/migration-2.2.rst | 6 +++---
 documentation/ref-manual/migration-2.3.rst | 6 +++---
 documentation/ref-manual/migration-2.4.rst | 6 +++---
 documentation/ref-manual/migration-2.5.rst | 6 +++---
 documentation/ref-manual/migration-2.6.rst | 6 +++---
 documentation/ref-manual/migration-2.7.rst | 6 +++---
 documentation/ref-manual/migration-3.0.rst | 6 +++---
 documentation/ref-manual/migration-3.1.rst | 6 +++---
 documentation/ref-manual/migration-3.2.rst | 6 +++---
 documentation/ref-manual/migration-3.3.rst | 6 +++---
 18 files changed, 54 insertions(+), 54 deletions(-)

diff --git a/documentation/ref-manual/migration-1.3.rst b/documentation/ref-manual/migration-1.3.rst
index 12e225b..0929f49 100644
--- a/documentation/ref-manual/migration-1.3.rst
+++ b/documentation/ref-manual/migration-1.3.rst
@@ -1,10 +1,10 @@
 .. SPDX-License-Identifier: CC-BY-SA-2.0-UK
 
-Moving to the Yocto Project 1.3 Release
-=======================================
+Moving to the Yocto Project 1.3 Release (danny)
+===============================================
 
 This section provides migration information for moving to the Yocto
-Project 1.3 Release from the prior release.
+Project 1.3 Release (codename "danny") from the prior release.
 
 .. _1.3-local-configuration:
 
diff --git a/documentation/ref-manual/migration-1.4.rst b/documentation/ref-manual/migration-1.4.rst
index 0b7e861..f5fac7a 100644
--- a/documentation/ref-manual/migration-1.4.rst
+++ b/documentation/ref-manual/migration-1.4.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 1.4 Release
-=======================================
+Moving to the Yocto Project 1.4 Release (dylan)
+===============================================
 
 This section provides migration information for moving to the Yocto
-Project 1.4 Release from the prior release.
+Project 1.4 Release (codename "dylan") from the prior release.
 
 .. _migration-1.4-bitbake:
 
diff --git a/documentation/ref-manual/migration-1.5.rst b/documentation/ref-manual/migration-1.5.rst
index 2d638f9..c772e51 100644
--- a/documentation/ref-manual/migration-1.5.rst
+++ b/documentation/ref-manual/migration-1.5.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 1.5 Release
-=======================================
+Moving to the Yocto Project 1.5 Release (dora)
+==============================================
 
 This section provides migration information for moving to the Yocto
-Project 1.5 Release from the prior release.
+Project 1.5 Release (codename "dora") from the prior release.
 
 .. _migration-1.5-host-dependency-changes:
 
diff --git a/documentation/ref-manual/migration-1.6.rst b/documentation/ref-manual/migration-1.6.rst
index ed155d0..4c6afab 100644
--- a/documentation/ref-manual/migration-1.6.rst
+++ b/documentation/ref-manual/migration-1.6.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 1.6 Release
-=======================================
+Moving to the Yocto Project 1.6 Release (daisy)
+===============================================
 
 This section provides migration information for moving to the Yocto
-Project 1.6 Release from the prior release.
+Project 1.6 Release (codename "daisy") from the prior release.
 
 .. _migration-1.6-archiver-class:
 
diff --git a/documentation/ref-manual/migration-1.7.rst b/documentation/ref-manual/migration-1.7.rst
index c00768c..9cf467f 100644
--- a/documentation/ref-manual/migration-1.7.rst
+++ b/documentation/ref-manual/migration-1.7.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 1.7 Release
-=======================================
+Moving to the Yocto Project 1.7 Release (dizzy)
+===============================================
 
 This section provides migration information for moving to the Yocto
-Project 1.7 Release from the prior release.
+Project 1.7 Release (codename "dizzy") from the prior release.
 
 .. _migration-1.7-changes-to-setting-qemu-packageconfig-options:
 
diff --git a/documentation/ref-manual/migration-1.8.rst b/documentation/ref-manual/migration-1.8.rst
index 73789bd..ec2b138 100644
--- a/documentation/ref-manual/migration-1.8.rst
+++ b/documentation/ref-manual/migration-1.8.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 1.8 Release
-=======================================
+Moving to the Yocto Project 1.8 Release (fido)
+==============================================
 
 This section provides migration information for moving to the Yocto
-Project 1.8 Release from the prior release.
+Project 1.8 Release (codename "fido") from the prior release.
 
 .. _migration-1.8-removed-recipes:
 
diff --git a/documentation/ref-manual/migration-2.0.rst b/documentation/ref-manual/migration-2.0.rst
index 4eea948..9da60df 100644
--- a/documentation/ref-manual/migration-2.0.rst
+++ b/documentation/ref-manual/migration-2.0.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 2.0 Release
-=======================================
+Moving to the Yocto Project 2.0 Release (jethro)
+================================================
 
 This section provides migration information for moving to the Yocto
-Project 2.0 Release from the prior release.
+Project 2.0 Release (codename "jethro") from the prior release.
 
 .. _migration-2.0-gcc-5:
 
diff --git a/documentation/ref-manual/migration-2.1.rst b/documentation/ref-manual/migration-2.1.rst
index b7bac0c..1eb9ab5 100644
--- a/documentation/ref-manual/migration-2.1.rst
+++ b/documentation/ref-manual/migration-2.1.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 2.1 Release
-=======================================
+Moving to the Yocto Project 2.1 Release (krogoth)
+=================================================
 
 This section provides migration information for moving to the Yocto
-Project 2.1 Release from the prior release.
+Project 2.1 Release (codename "krogoth") from the prior release.
 
 .. _migration-2.1-variable-expansion-in-python-functions:
 
diff --git a/documentation/ref-manual/migration-2.2.rst b/documentation/ref-manual/migration-2.2.rst
index 8b3c5d6..198181a 100644
--- a/documentation/ref-manual/migration-2.2.rst
+++ b/documentation/ref-manual/migration-2.2.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 2.2 Release
-=======================================
+Moving to the Yocto Project 2.2 Release (morty)
+===============================================
 
 This section provides migration information for moving to the Yocto
-Project 2.2 Release from the prior release.
+Project 2.2 Release (codename "morty") from the prior release.
 
 .. _migration-2.2-minimum-kernel-version:
 
diff --git a/documentation/ref-manual/migration-2.3.rst b/documentation/ref-manual/migration-2.3.rst
index 04b11da..0541eb3 100644
--- a/documentation/ref-manual/migration-2.3.rst
+++ b/documentation/ref-manual/migration-2.3.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 2.3 Release
-=======================================
+Moving to the Yocto Project 2.3 Release (pyro)
+==============================================
 
 This section provides migration information for moving to the Yocto
-Project 2.3 Release from the prior release.
+Project 2.3 Release (codename "pyro") from the prior release.
 
 .. _migration-2.3-recipe-specific-sysroots:
 
diff --git a/documentation/ref-manual/migration-2.4.rst b/documentation/ref-manual/migration-2.4.rst
index 260b320..2ba17e0 100644
--- a/documentation/ref-manual/migration-2.4.rst
+++ b/documentation/ref-manual/migration-2.4.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 2.4 Release
-=======================================
+Moving to the Yocto Project 2.4 Release (rocko)
+===============================================
 
 This section provides migration information for moving to the Yocto
-Project 2.4 Release from the prior release.
+Project 2.4 Release (codename "rocko") from the prior release.
 
 .. _migration-2.4-memory-resident-mode:
 
diff --git a/documentation/ref-manual/migration-2.5.rst b/documentation/ref-manual/migration-2.5.rst
index 9f45ffc..9ef4b55 100644
--- a/documentation/ref-manual/migration-2.5.rst
+++ b/documentation/ref-manual/migration-2.5.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 2.5 Release
-=======================================
+Moving to the Yocto Project 2.5 Release (sumo)
+==============================================
 
 This section provides migration information for moving to the Yocto
-Project 2.5 Release from the prior release.
+Project 2.5 Release (codename "sumo") from the prior release.
 
 .. _migration-2.5-packaging-changes:
 
diff --git a/documentation/ref-manual/migration-2.6.rst b/documentation/ref-manual/migration-2.6.rst
index 823d3cb..aeac509 100644
--- a/documentation/ref-manual/migration-2.6.rst
+++ b/documentation/ref-manual/migration-2.6.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 2.6 Release
-=======================================
+Moving to the Yocto Project 2.6 Release (thud)
+==============================================
 
 This section provides migration information for moving to the Yocto
-Project 2.6 Release from the prior release.
+Project 2.6 Release (codename "thud") from the prior release.
 
 .. _migration-2.6-gcc-changes:
 
diff --git a/documentation/ref-manual/migration-2.7.rst b/documentation/ref-manual/migration-2.7.rst
index 5af5947..1be4d5d 100644
--- a/documentation/ref-manual/migration-2.7.rst
+++ b/documentation/ref-manual/migration-2.7.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 2.7 Release
-=======================================
+Moving to the Yocto Project 2.7 Release (warrior)
+=================================================
 
 This section provides migration information for moving to the Yocto
-Project 2.7 Release from the prior release.
+Project 2.7 Release (codename "warrior") from the prior release.
 
 .. _migration-2.7-bitbake-changes:
 
diff --git a/documentation/ref-manual/migration-3.0.rst b/documentation/ref-manual/migration-3.0.rst
index 7ef2742..f3d20e2 100644
--- a/documentation/ref-manual/migration-3.0.rst
+++ b/documentation/ref-manual/migration-3.0.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 3.0 Release
-=======================================
+Moving to the Yocto Project 3.0 Release (zeus)
+==============================================
 
 This section provides migration information for moving to the Yocto
-Project 3.0 Release from the prior release.
+Project 3.0 Release (codename "zeus") from the prior release.
 
 .. _migration-3.0-init-system-selection:
 
diff --git a/documentation/ref-manual/migration-3.1.rst b/documentation/ref-manual/migration-3.1.rst
index 4fcd249..84d3250 100644
--- a/documentation/ref-manual/migration-3.1.rst
+++ b/documentation/ref-manual/migration-3.1.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 3.1 Release
-=======================================
+Moving to the Yocto Project 3.1 Release (dunfell)
+=================================================
 
 This section provides migration information for moving to the Yocto
-Project 3.1 Release from the prior release.
+Project 3.1 Release (codename "dunfell") from the prior release.
 
 .. _migration-3.1-minimum-system-requirements:
 
diff --git a/documentation/ref-manual/migration-3.2.rst b/documentation/ref-manual/migration-3.2.rst
index cca8124..39743af 100644
--- a/documentation/ref-manual/migration-3.2.rst
+++ b/documentation/ref-manual/migration-3.2.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 3.2 Release
-=======================================
+Moving to the Yocto Project 3.2 Release (gatesgarth)
+====================================================
 
 This section provides migration information for moving to the Yocto
-Project 3.2 Release from the prior release.
+Project 3.2 Release (codename "gatesgarth") from the prior release.
 
 .. _migration-3.2-minimum-system-requirements:
 
diff --git a/documentation/ref-manual/migration-3.3.rst b/documentation/ref-manual/migration-3.3.rst
index 8dfbe7f..ff010fd 100644
--- a/documentation/ref-manual/migration-3.3.rst
+++ b/documentation/ref-manual/migration-3.3.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 3.3 Release
-=======================================
+Moving to the Yocto Project 3.3 Release (hardknott)
+===================================================
 
 This section provides migration information for moving to the Yocto
-Project 3.3 Release from the prior release.
+Project 3.3 Release (codename "hardknott") from the prior release.
 
 
 .. _migration-3.3-minimum-system-requirements:
-- 
1.8.3.1

Re: [docs] [PATCH 01/13] ref-manual: add METADATA_REVISION and METADATA_BRANCH

[Quentin Schulz]

Hi Paul,

On Tue, Apr 13, 2021 at 05:19:42PM -0700, Paul Eggleton wrote:
> From: Paul Eggleton <paul.eggleton@microsoft.com>
> 
> These are not new variables, but we are using METADATA_REVISION in a new
> place and thus need to refer to it.
> 
> Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
> ---
>  documentation/ref-manual/variables.rst | 8 ++++++++
>  1 file changed, 8 insertions(+)
> 
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 19f5e34..de63046 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -4659,6 +4659,14 @@ system and gives an overview of their function and contents.
>     :term:`MAINTAINER`
>        The email address of the distribution maintainer.
>  
> +   :term:`METADATA_BRANCH`
> +      The branch currently checked out for the core layer (path determined by
> +      :term:`COREBASE`).
> +
> +   :term:`METADATA_REVISION`
> +      The revision currently checked out for the core layer (path determined by
> +      :term:`COREBASE`).
> +

Would it make sense to explicit which is the core layer? I assume it is
openembedded-core layer which is poky/meta too. Just to explicit a bit
more.

Also, if they really aren't new variables, could you please send
backport patches to the appropriate branches once it's merged in master?

Thanks!

Cheers,
Quentin

Re: [docs] [PATCH 05/13] ref-manual: and SDK_CUSTOM_TEMPLATECONF to glossary

[Quentin Schulz]

Hi Paul,

On Tue, Apr 13, 2021 at 05:19:46PM -0700, Paul Eggleton wrote:
> From: Paul Eggleton <paul.eggleton@microsoft.com>
> 
> Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
> ---
>  documentation/ref-manual/variables.rst | 5 +++++
>  1 file changed, 5 insertions(+)
> 
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index b9478a3..ef61339 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -6489,6 +6489,11 @@ system and gives an overview of their function and contents.
>        The target architecture for the SDK. Typically, you do not directly
>        set this variable. Instead, use :term:`SDKMACHINE`.
>  
> +   :term:`SDK_CUSTOM_TEMPLATECONF`
> +      When building the extensible SDK, if ``SDK_CUSTOM_TEMPLATECONF`` is set to
> +      "1" and a ``conf/templateconf.conf`` file exists in the build directory
> +      (``TOPDIR``) then this will be copied into the SDK.

s/``TOPDIR``/:term:`TOPDIR`/

Thanks,
Quentin

Re: [docs] [PATCH 06/13] ref-manual: add REQUIRED_VERSION and adjust PREFERRED_VERSION entry

[Quentin Schulz]

Hi Paul,

Just nitpicking.

On Tue, Apr 13, 2021 at 05:19:47PM -0700, Paul Eggleton wrote:
> From: Paul Eggleton <paul.eggleton@microsoft.com>
> 
> Add REQUIRED_VERSION, add a reference to it in PREFERRED_VERSION and
> adjust the opening statement to read slightly better.
> 
> Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
> ---
>  documentation/ref-manual/variables.rst | 22 ++++++++++++++++++----
>  1 file changed, 18 insertions(+), 4 deletions(-)
> 
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index ef61339..a97f858 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -5798,10 +5798,10 @@ system and gives an overview of their function and contents.
>           exclusive alternative providers.
>  
>     :term:`PREFERRED_VERSION`
> -      If multiple versions of recipes exist, this variable determines which
> -      version is given preference. You must always suffix the variable with
> -      the :term:`PN` you want to select, and you should set the
> -      :term:`PV` accordingly for precedence.
> +      If there are multiple versions of a recipe available, this variable
> +      determines which version should be given preference. You must always
> +      suffix the variable with the :term:`PN` you want to select, and you
> +      should set the :term:`PV` accordingly for precedence.
>  

Would it make sense to explicit what suffixing with PN and specifying PV mean?
We have an example just a few lines below, so I'd see something like:

suffix the variable with the :term:`PN` you want to select (`python` in
the example below), and you should set the :term:`PV` accordingly
(`3.4.0` in the example).

>        The ``PREFERRED_VERSION`` variable supports limited wildcard use
>        through the "``%``" character. You can use the character to match any
> @@ -5859,6 +5859,10 @@ system and gives an overview of their function and contents.
>           The ``\_forcevariable`` override is not handled specially. This override
>           only works because the default value of ``OVERRIDES`` includes "forcevariable".
>  
> +      If a recipe with the specified version is not available, a warning
> +      message will be shown. See :term:`REQUIRED_VERSION` if you want this
> +      to be an error instead.
> +
>     :term:`PREMIRRORS`
>        Specifies additional paths from which the OpenEmbedded build system
>        gets source code. When the build system searches for source code, it
> @@ -6216,6 +6220,16 @@ system and gives an overview of their function and contents.
>        the recipe will be skipped, and if the build system attempts to build
>        the recipe then an error will be triggered.
>  
> +   :term:`REQUIRED_VERSION`
> +      If there are multiple versions of a recipe available, this variable
> +      determines which version should be given preference. ``REQUIRED_VERSION``
> +      works in exactly the same manner as :term:`PREFERRED_VERSION`, except
> +      that if the specified version is not available then an error message
> +      is shown and the build fails immediately.
> +
> +      If both ``REQUIRED_VERSION`` and ``PREFERRED_VERSION`` are set for

I think we wanted to go for using :term: for every occurence of a
variable (which is *definitely* not something we've done so far), so I'd
suggest s/``PREFERRED_VERSION``/:term:`PREFERRED_VERSION`/ here. For me
REQUIRED_VERSION does not warrant the use of term because it is used in
the paragraph defining it (but maybe it's something we want?).

Cheers,
Quentin

Re: [docs] [PATCH 08/13] ref-manual: add passwd-expire to EXTRA_USERS_PARAMS

[Quentin Schulz]

Hi Paul,

On Tue, Apr 13, 2021 at 05:19:49PM -0700, Paul Eggleton wrote:
> From: Paul Eggleton <paul.eggleton@microsoft.com>
> 
> Add a reference to the recently added passwd-expire command in
> EXTRA_USERS_PARAMS.
> 
> Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
> ---
>  documentation/ref-manual/variables.rst | 11 +++++++++++
>  1 file changed, 11 insertions(+)
> 
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 2e3cc22..3b76dbc 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -2293,6 +2293,17 @@ system and gives an overview of their function and contents.
>           # usermod -s /bin/sh tester; \
>           # "
>  
> +      Additionally there is a special ``passwd-expire`` command that will
> +      cause the password for a user to be expired and thus force changing it
> +      on first login, for example: ::
> +

IIRC, :: will behave the same as : ::, so please use the former (trying to
have consistency across all docs, though we're far from it now :|, but
this change is something we want).

Pinging @Nicolas just for confirmation :)

Thanks,
Quentin

Re: [docs] [PATCH 09/13] ref-manual: add FIT_KERNEL_COMP_ALG*

[Quentin Schulz]

Hi Paul,

On Tue, Apr 13, 2021 at 05:19:50PM -0700, Paul Eggleton wrote:
> From: Paul Eggleton <paul.eggleton@microsoft.com>
> 
> Add FIT_KERNEL_COMP_ALG and FIT_KERNEL_COMP_ALG_EXTENSION. Examining
> OE-Core commit 5c72105e2973e613b5c0f0e6310ffdea6e56c6c7 and the
> associated code, these do not enable arbitrary selection of compression
> algorithm - only disabling compression - so document them accordingly.
> 
> Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
> ---
>  documentation/ref-manual/variables.rst | 11 +++++++++++
>  1 file changed, 11 insertions(+)
> 
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 3b76dbc..f010cd7 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -2580,6 +2580,17 @@ system and gives an overview of their function and contents.
>     :term:`FIT_HASH_ALG`
>        Specifies the hash algorithm used in creating the FIT Image. For e.g. sha256.
>  
> +   :term:`FIT_KERNEL_COMP_ALG`
> +      Compression algorithm to use for the kernel image inside the fitImage.
> +      At present, the only supported values are "gzip" (default) or "none",
> +      which allows disabling of compression if it would otherwise be enabled.

I'm not a native speaker and I'm struggling to understand that last line,
would it be possible for you to rephrase please?

> +      If you set this you will also need to set :term:`FIT_KERNEL_COMP_ALG_EXTENSION`.
> +
> +   :term:`FIT_KERNEL_COMP_ALG_EXTENSION`
> +      File extension corresponding to :term:`FIT_KERNEL_COMP_ALG`. The default
> +      value is ".gz"; if you set ``FIT_KERNEL_COMP_ALG`` to "none" then

s/``FIT_KERNEL_COMP_ALG``/:term:`FIT_KERNEL_COMP_ALG`/

Thanks,
Quentin

Re: [docs] [PATCH 06/13] ref-manual: add REQUIRED_VERSION and adjust PREFERRED_VERSION entry

[Nicolas Dechesne]

[-- Attachment #1: Type: text/plain, Size: 4126 bytes --]

On Wed, Apr 14, 2021 at 10:10 AM Quentin Schulz <
quentin.schulz@streamunlimited.com> wrote:

> Hi Paul,
>
> Just nitpicking.
>
> On Tue, Apr 13, 2021 at 05:19:47PM -0700, Paul Eggleton wrote:
> > From: Paul Eggleton <paul.eggleton@microsoft.com>
> >
> > Add REQUIRED_VERSION, add a reference to it in PREFERRED_VERSION and
> > adjust the opening statement to read slightly better.
> >
> > Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
> > ---
> >  documentation/ref-manual/variables.rst | 22 ++++++++++++++++++----
> >  1 file changed, 18 insertions(+), 4 deletions(-)
> >
> > diff --git a/documentation/ref-manual/variables.rst
> b/documentation/ref-manual/variables.rst
> > index ef61339..a97f858 100644
> > --- a/documentation/ref-manual/variables.rst
> > +++ b/documentation/ref-manual/variables.rst
> > @@ -5798,10 +5798,10 @@ system and gives an overview of their function
> and contents.
> >           exclusive alternative providers.
> >
> >     :term:`PREFERRED_VERSION`
> > -      If multiple versions of recipes exist, this variable determines
> which
> > -      version is given preference. You must always suffix the variable
> with
> > -      the :term:`PN` you want to select, and you should set the
> > -      :term:`PV` accordingly for precedence.
> > +      If there are multiple versions of a recipe available, this
> variable
> > +      determines which version should be given preference. You must
> always
> > +      suffix the variable with the :term:`PN` you want to select, and
> you
> > +      should set the :term:`PV` accordingly for precedence.
> >
>
> Would it make sense to explicit what suffixing with PN and specifying PV
> mean?
> We have an example just a few lines below, so I'd see something like:
>
> suffix the variable with the :term:`PN` you want to select (`python` in
> the example below), and you should set the :term:`PV` accordingly
> (`3.4.0` in the example).
>
> >        The ``PREFERRED_VERSION`` variable supports limited wildcard use
> >        through the "``%``" character. You can use the character to match
> any
> > @@ -5859,6 +5859,10 @@ system and gives an overview of their function
> and contents.
> >           The ``\_forcevariable`` override is not handled specially.
> This override
> >           only works because the default value of ``OVERRIDES`` includes
> "forcevariable".
> >
> > +      If a recipe with the specified version is not available, a warning
> > +      message will be shown. See :term:`REQUIRED_VERSION` if you want
> this
> > +      to be an error instead.
> > +
> >     :term:`PREMIRRORS`
> >        Specifies additional paths from which the OpenEmbedded build
> system
> >        gets source code. When the build system searches for source code,
> it
> > @@ -6216,6 +6220,16 @@ system and gives an overview of their function
> and contents.
> >        the recipe will be skipped, and if the build system attempts to
> build
> >        the recipe then an error will be triggered.
> >
> > +   :term:`REQUIRED_VERSION`
> > +      If there are multiple versions of a recipe available, this
> variable
> > +      determines which version should be given preference.
> ``REQUIRED_VERSION``
> > +      works in exactly the same manner as :term:`PREFERRED_VERSION`,
> except
> > +      that if the specified version is not available then an error
> message
> > +      is shown and the build fails immediately.
> > +
> > +      If both ``REQUIRED_VERSION`` and ``PREFERRED_VERSION`` are set for
>
> I think we wanted to go for using :term: for every occurence of a
> variable (which is *definitely* not something we've done so far), so I'd
> suggest s/``PREFERRED_VERSION``/:term:`PREFERRED_VERSION`/ here. For me
> REQUIRED_VERSION does not warrant the use of term because it is used in
> the paragraph defining it (but maybe it's something we want?).
>

Looking (far) ahead, if we assume we can render :term: with a proper style,
then I think it makes sense to use it everywhere, even here.


>
> Cheers,
> Quentin
>
> 
>
>

[-- Attachment #2: Type: text/html, Size: 5155 bytes --]

Re: [docs] [PATCH 10/13] ref-manual: fix reference to build-essential

[Quentin Schulz]

Hi Paul,

On Tue, Apr 13, 2021 at 05:19:51PM -0700, Paul Eggleton wrote:
> From: Paul Eggleton <paul.eggleton@microsoft.com>
> 
> This has been here since the text was added to the DocBook version.
> 
> Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
> ---
>  documentation/ref-manual/system-requirements.rst | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/documentation/ref-manual/system-requirements.rst b/documentation/ref-manual/system-requirements.rst
> index dc619ce..2e2d0d3 100644
> --- a/documentation/ref-manual/system-requirements.rst
> +++ b/documentation/ref-manual/system-requirements.rst
> @@ -274,7 +274,8 @@ version requirement for gcc:
>  
>  If your host development system does not meet this requirement, you can
>  resolve this by installing a ``buildtools-extended`` tarball that
> -contains additional tools, the equivalent of ``buildtools-essential``.
> +contains additional tools, the equivalent of the Debian/Ubuntu ``build-essential``
> +package.
>  
>  Installing a Pre-Built ``buildtools`` Tarball with ``install-buildtools`` script
>  --------------------------------------------------------------------------------
> -- 
> 1.8.3.1
> 

Thanks for the patch. Please send a backport patch once merged for still
maintained Sphinx-using releases of the docs. (dunfell and gatesgarth I
guess?).

Cheers,
Quentin

Re: [docs] [PATCH 08/13] ref-manual: add passwd-expire to EXTRA_USERS_PARAMS

[Nicolas Dechesne]

[-- Attachment #1: Type: text/plain, Size: 1551 bytes --]

On Wed, Apr 14, 2021 at 10:13 AM Quentin Schulz <
quentin.schulz@streamunlimited.com> wrote:

> Hi Paul,
>
> On Tue, Apr 13, 2021 at 05:19:49PM -0700, Paul Eggleton wrote:
> > From: Paul Eggleton <paul.eggleton@microsoft.com>
> >
> > Add a reference to the recently added passwd-expire command in
> > EXTRA_USERS_PARAMS.
> >
> > Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
> > ---
> >  documentation/ref-manual/variables.rst | 11 +++++++++++
> >  1 file changed, 11 insertions(+)
> >
> > diff --git a/documentation/ref-manual/variables.rst
> b/documentation/ref-manual/variables.rst
> > index 2e3cc22..3b76dbc 100644
> > --- a/documentation/ref-manual/variables.rst
> > +++ b/documentation/ref-manual/variables.rst
> > @@ -2293,6 +2293,17 @@ system and gives an overview of their function
> and contents.
> >           # usermod -s /bin/sh tester; \
> >           # "
> >
> > +      Additionally there is a special ``passwd-expire`` command that
> will
> > +      cause the password for a user to be expired and thus force
> changing it
> > +      on first login, for example: ::
> > +
>
> IIRC, :: will behave the same as : ::, so please use the former (trying to
> have consistency across all docs, though we're far from it now :|, but
> this change is something we want).
>
> Pinging @Nicolas just for confirmation :)
>

Yes, agreed. There was a patch floating around to convert all instances of
: :: into ::, not sure if it was merged or dropped..


>
> Thanks,
> Quentin
>
> 
>
>

[-- Attachment #2: Type: text/html, Size: 2342 bytes --]

Re: [docs] [PATCH 10/13] ref-manual: fix reference to build-essential

[Nicolas Dechesne]

[-- Attachment #1: Type: text/plain, Size: 1846 bytes --]

On Wed, Apr 14, 2021 at 10:18 AM Quentin Schulz <
quentin.schulz@streamunlimited.com> wrote:

> Hi Paul,
>
> On Tue, Apr 13, 2021 at 05:19:51PM -0700, Paul Eggleton wrote:
> > From: Paul Eggleton <paul.eggleton@microsoft.com>
> >
> > This has been here since the text was added to the DocBook version.
> >
> > Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
> > ---
> >  documentation/ref-manual/system-requirements.rst | 3 ++-
> >  1 file changed, 2 insertions(+), 1 deletion(-)
> >
> > diff --git a/documentation/ref-manual/system-requirements.rst
> b/documentation/ref-manual/system-requirements.rst
> > index dc619ce..2e2d0d3 100644
> > --- a/documentation/ref-manual/system-requirements.rst
> > +++ b/documentation/ref-manual/system-requirements.rst
> > @@ -274,7 +274,8 @@ version requirement for gcc:
> >
> >  If your host development system does not meet this requirement, you can
> >  resolve this by installing a ``buildtools-extended`` tarball that
> > -contains additional tools, the equivalent of ``buildtools-essential``.
> > +contains additional tools, the equivalent of the Debian/Ubuntu
> ``build-essential``
> > +package.
> >
> >  Installing a Pre-Built ``buildtools`` Tarball with
> ``install-buildtools`` script
> >
> --------------------------------------------------------------------------------
> > --
> > 1.8.3.1
> >
>
> Thanks for the patch. Please send a backport patch once merged for still
> maintained Sphinx-using releases of the docs. (dunfell and gatesgarth I
> guess?).
>

Yes, I had this thought when I glanced at the patches too. I am not sure
how/if the LTS/stable process applies to yocto-docs. Are the LTS and stable
maintainers doing an active backports, or we do have to send all relevant
patches to them?


>
> Cheers,
> Quentin
>
> 
>
>

[-- Attachment #2: Type: text/html, Size: 2628 bytes --]

Re: [docs] [PATCH 12/13] ref-manual: add migration section for 3.3 release

[Quentin Schulz]

Hi Paul,

On Tue, Apr 13, 2021 at 05:19:53PM -0700, Paul Eggleton wrote:
> From: Paul Eggleton <paul.eggleton@microsoft.com>
> 
> Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
> ---
>  documentation/ref-manual/migration-3.3.rst | 144 +++++++++++++++++++++++++++++
>  documentation/ref-manual/migration.rst     |   1 +
>  2 files changed, 145 insertions(+)
>  create mode 100644 documentation/ref-manual/migration-3.3.rst
> 
> diff --git a/documentation/ref-manual/migration-3.3.rst b/documentation/ref-manual/migration-3.3.rst
> new file mode 100644
> index 0000000..8dfbe7f
> --- /dev/null
> +++ b/documentation/ref-manual/migration-3.3.rst
> @@ -0,0 +1,144 @@
> +Moving to the Yocto Project 3.3 Release
> +=======================================
> +
> +This section provides migration information for moving to the Yocto
> +Project 3.3 Release from the prior release.
> +
> +
> +.. _migration-3.3-minimum-system-requirements:
> +
> +Minimum system requirements
> +---------------------------
> +
> +You will now need at least Python 3.6 installed on your build host. Most recent
> +distributions provide this, but should you be building on a distribution that
> +does not have it, you can use the ``buildtools-tarball`` (easily installable
> +using ``scripts/install-buildtools``) - see
> +:ref:`ref-manual/system-requirements:required git, tar, python and gcc versions`
> +for details.
> +
> +
> +.. _migration-3.3-removed-recipes:
> +
> +Removed recipes
> +---------------
> +
> +The following recipes have been removed:
> +
> +- ``go-dep``: obsolete with the advent of go modules
> +- ``gst-validate``: replaced by ``gst-devtools``
> +- ``linux-yocto``: removed 5.8 version recipes (5.4 / 5.10 still provided)
> +- ``vulkan-demos``: replaced by ``vulkan-samples``
> +
> +
> +.. _migration-3.3-common-license-only-versions:
> +
> +Single version common license file naming
> +-----------------------------------------
> +
> +Some license files in ``meta/files/common-licenses`` have been renamed to match
> +current SPDX naming conventions:
> +
> +- AGPL-3.0 -> AGPL-3.0-only
> +- GPL-1.0 -> GPL-1.0-only
> +- GPL-2.0 -> GPL-2.0-only
> +- GPL-3.0 -> GPL-3.0-only
> +- LGPL-2.0 -> LGPL-2.0-only
> +- LGPL-2.1 -> LGPL-2.1-only
> +- LGPL-3.0 -> LGPL-3.0-only
> +
> +Additionally, corresponding "-or-later" suffixed files have been added e.g.
> +``GPL-2.0-or-later``.
> +
> +It is not required that you change :term:`LICENSE` values as there are mappings
> +from the original names in place; however, in rare cases where you have a recipe
> +which sets :term:`LIC_FILES_CHKSUM` to point to file(s) in
> +``meta/files/common-licenses`` (which in any case is not recommended) you will
> +need to update those.
> +
> +
> +.. _migration-3.3-python3targetconfig:
> +
> +New ``python3targetconfig`` class
> +---------------------------------
> +
> +A new :ref:`python3targetconfig <ref-classes-python3targetconfig>` class has been
> +created for situations where you would previously have inherited the
> +``python3native`` class but need access to target configuration data (such as
> +correct installation directories). Recipes where this situation applies should
> +be changed to inherit ``python3targetconfig`` instead of ``python3native``. This
> +also adds a dependency on target ``python3``, so it should only be used where
> +appropriate in order to avoid unnecessarily lengthening builds.
> +
> +Some example recipes where this change has been made: ``gpgme``, ``libcap-ng``,
> +``python3-pycairo``.
> +
> +
> +.. _migration-3.3-bitbake:
> +
> +BitBake changes
> +---------------
> +
> +- BitBake is now configured to use a default ``umask`` of ``022`` for all tasks
> +  (specified via a new ``BB_DEFAULT_UMASK`` variable). If needed, ``umask`` can

s/``BB_DEFAULT_UMASK``/:term:`BB_DEFAULT_UMASK`/

IIRC, this works fine even for bitbake terms (might need some tweaking
if it does not work but I know we use :term: for some bitbake variables
from bitbake's docs).

Cheers,
Quentin

> +  still be set on a per-task basis via the ``umask`` varflag on the task
> +  function, but that is unlikely to be necessary in most cases.
> +
> +- If a version specified in :term:`PREFERRED_VERSION` is not available this
> +  will now trigger a warning instead of just a note, making such issues more
> +  visible.
> +
> +
> +.. _migration-3.3-packaging:
> +
> +Packaging changes
> +-----------------
> +
> +The following packaging changes have been made; in all cases the main package
> +still depends upon the split out packages so you should not need to do anything
> +unless you want to take advantage of the improved granularity:
> +
> +- ``dbus``: ``-common`` and ``-tools`` split out
> +- ``iproute2``: split ip binary to its own package

s/ip/``ip``/

> +- ``net-tools``: split ``mii-tool`` into its own package
> +- ``procps``: split ``ps`` and ``sysctl`` into their own packages
> +- ``rpm``: split build and extra functionality into separate packages
> +- ``sudo``: split ``sudo`` binary into ``sudo-sudo`` and libs into ``sudo-lib``
> +- ``systemtap``: examples, python scripts and runtime material split out
> +- ``util-linux``: ``libuuid`` has been split out to its own
> +  ``util-linux-libuuid`` recipe (and corresponding packages) to avoid circular
> +  dependencies if ``libgcrypt`` support is enabled in ``util-linux``.
> +  (``util-linux`` depends upon ``util-linux-libuuid``.)
> +
> +
> +.. _migration-3.3-misc:
> +
> +Miscellaneous changes
> +---------------------
> +
> +- The default poky :term:`DISTRO_VERSION` value now uses the core metadata's
> +  git hash (i.e. :term:`METADATA_REVISION`) rather than the date (i.e.
> +  :term:`DATE`) to reduce one small source of non-reproducibility. You can
> +  of course specify your own ``DISTRO_VERSION`` value as desired

s/``DISTRO_VERSION``/:term:`DISTRO_VERSION`/

> +  (particularly if you create your own custom distro configuration).
> +- The :ref:`ccache <ref-classes-ccache>` class now uses ``ccache`` from the
> +  build host rather than building ``ccache-native`` (due to circular
> +  dependencies in ccache 4.0 that are impractical to resolve otherwise), so
> +  if you enable it you will now need to have ``ccache`` installed on your
> +  host system.

Will a warning be shown if ccache is not installed on the host or does
it silently fail to use ccache?

Would be nice to mention if there's a warning/error message being shown
so that at least the user knows if they should take extra care to verify
it is installed (and used).

Cheers,
Quentin

Re: [docs] [PATCH 13/13] ref-manual: migration guide: add release codenames

[Quentin Schulz]

Hi Paul,

Very nice addition. We need to do the same in the dropdown menu for doc
release selection (it's already been discussed, just need someone to
start working on it :) ).

Once merged, could you please send backport patch to dunfell and
gatesgarth :) ?

Thanks!
Quentin

On Tue, Apr 13, 2021 at 05:19:54PM -0700, Paul Eggleton wrote:
> From: Paul Eggleton <paul.eggleton@microsoft.com>
> 
> People will see release codenames in other contexts, and thus it is
> useful to mention them explicitly here rather than having to go to the
> Releases wiki page to map version number to release codename.
> 
> Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
> ---
>  documentation/ref-manual/migration-1.3.rst | 6 +++---
>  documentation/ref-manual/migration-1.4.rst | 6 +++---
>  documentation/ref-manual/migration-1.5.rst | 6 +++---
>  documentation/ref-manual/migration-1.6.rst | 6 +++---
>  documentation/ref-manual/migration-1.7.rst | 6 +++---
>  documentation/ref-manual/migration-1.8.rst | 6 +++---
>  documentation/ref-manual/migration-2.0.rst | 6 +++---
>  documentation/ref-manual/migration-2.1.rst | 6 +++---
>  documentation/ref-manual/migration-2.2.rst | 6 +++---
>  documentation/ref-manual/migration-2.3.rst | 6 +++---
>  documentation/ref-manual/migration-2.4.rst | 6 +++---
>  documentation/ref-manual/migration-2.5.rst | 6 +++---
>  documentation/ref-manual/migration-2.6.rst | 6 +++---
>  documentation/ref-manual/migration-2.7.rst | 6 +++---
>  documentation/ref-manual/migration-3.0.rst | 6 +++---
>  documentation/ref-manual/migration-3.1.rst | 6 +++---
>  documentation/ref-manual/migration-3.2.rst | 6 +++---
>  documentation/ref-manual/migration-3.3.rst | 6 +++---
>  18 files changed, 54 insertions(+), 54 deletions(-)
> 
> diff --git a/documentation/ref-manual/migration-1.3.rst b/documentation/ref-manual/migration-1.3.rst
> index 12e225b..0929f49 100644
> --- a/documentation/ref-manual/migration-1.3.rst
> +++ b/documentation/ref-manual/migration-1.3.rst
> @@ -1,10 +1,10 @@
>  .. SPDX-License-Identifier: CC-BY-SA-2.0-UK
>  
> -Moving to the Yocto Project 1.3 Release
> -=======================================
> +Moving to the Yocto Project 1.3 Release (danny)
> +===============================================
>  
>  This section provides migration information for moving to the Yocto
> -Project 1.3 Release from the prior release.
> +Project 1.3 Release (codename "danny") from the prior release.
>  
>  .. _1.3-local-configuration:
>  
> diff --git a/documentation/ref-manual/migration-1.4.rst b/documentation/ref-manual/migration-1.4.rst
> index 0b7e861..f5fac7a 100644
> --- a/documentation/ref-manual/migration-1.4.rst
> +++ b/documentation/ref-manual/migration-1.4.rst
> @@ -1,8 +1,8 @@
> -Moving to the Yocto Project 1.4 Release
> -=======================================
> +Moving to the Yocto Project 1.4 Release (dylan)
> +===============================================
>  
>  This section provides migration information for moving to the Yocto
> -Project 1.4 Release from the prior release.
> +Project 1.4 Release (codename "dylan") from the prior release.
>  
>  .. _migration-1.4-bitbake:
>  
> diff --git a/documentation/ref-manual/migration-1.5.rst b/documentation/ref-manual/migration-1.5.rst
> index 2d638f9..c772e51 100644
> --- a/documentation/ref-manual/migration-1.5.rst
> +++ b/documentation/ref-manual/migration-1.5.rst
> @@ -1,8 +1,8 @@
> -Moving to the Yocto Project 1.5 Release
> -=======================================
> +Moving to the Yocto Project 1.5 Release (dora)
> +==============================================
>  
>  This section provides migration information for moving to the Yocto
> -Project 1.5 Release from the prior release.
> +Project 1.5 Release (codename "dora") from the prior release.
>  
>  .. _migration-1.5-host-dependency-changes:
>  
> diff --git a/documentation/ref-manual/migration-1.6.rst b/documentation/ref-manual/migration-1.6.rst
> index ed155d0..4c6afab 100644
> --- a/documentation/ref-manual/migration-1.6.rst
> +++ b/documentation/ref-manual/migration-1.6.rst
> @@ -1,8 +1,8 @@
> -Moving to the Yocto Project 1.6 Release
> -=======================================
> +Moving to the Yocto Project 1.6 Release (daisy)
> +===============================================
>  
>  This section provides migration information for moving to the Yocto
> -Project 1.6 Release from the prior release.
> +Project 1.6 Release (codename "daisy") from the prior release.
>  
>  .. _migration-1.6-archiver-class:
>  
> diff --git a/documentation/ref-manual/migration-1.7.rst b/documentation/ref-manual/migration-1.7.rst
> index c00768c..9cf467f 100644
> --- a/documentation/ref-manual/migration-1.7.rst
> +++ b/documentation/ref-manual/migration-1.7.rst
> @@ -1,8 +1,8 @@
> -Moving to the Yocto Project 1.7 Release
> -=======================================
> +Moving to the Yocto Project 1.7 Release (dizzy)
> +===============================================
>  
>  This section provides migration information for moving to the Yocto
> -Project 1.7 Release from the prior release.
> +Project 1.7 Release (codename "dizzy") from the prior release.
>  
>  .. _migration-1.7-changes-to-setting-qemu-packageconfig-options:
>  
> diff --git a/documentation/ref-manual/migration-1.8.rst b/documentation/ref-manual/migration-1.8.rst
> index 73789bd..ec2b138 100644
> --- a/documentation/ref-manual/migration-1.8.rst
> +++ b/documentation/ref-manual/migration-1.8.rst
> @@ -1,8 +1,8 @@
> -Moving to the Yocto Project 1.8 Release
> -=======================================
> +Moving to the Yocto Project 1.8 Release (fido)
> +==============================================
>  
>  This section provides migration information for moving to the Yocto
> -Project 1.8 Release from the prior release.
> +Project 1.8 Release (codename "fido") from the prior release.
>  
>  .. _migration-1.8-removed-recipes:
>  
> diff --git a/documentation/ref-manual/migration-2.0.rst b/documentation/ref-manual/migration-2.0.rst
> index 4eea948..9da60df 100644
> --- a/documentation/ref-manual/migration-2.0.rst
> +++ b/documentation/ref-manual/migration-2.0.rst
> @@ -1,8 +1,8 @@
> -Moving to the Yocto Project 2.0 Release
> -=======================================
> +Moving to the Yocto Project 2.0 Release (jethro)
> +================================================
>  
>  This section provides migration information for moving to the Yocto
> -Project 2.0 Release from the prior release.
> +Project 2.0 Release (codename "jethro") from the prior release.
>  
>  .. _migration-2.0-gcc-5:
>  
> diff --git a/documentation/ref-manual/migration-2.1.rst b/documentation/ref-manual/migration-2.1.rst
> index b7bac0c..1eb9ab5 100644
> --- a/documentation/ref-manual/migration-2.1.rst
> +++ b/documentation/ref-manual/migration-2.1.rst
> @@ -1,8 +1,8 @@
> -Moving to the Yocto Project 2.1 Release
> -=======================================
> +Moving to the Yocto Project 2.1 Release (krogoth)
> +=================================================
>  
>  This section provides migration information for moving to the Yocto
> -Project 2.1 Release from the prior release.
> +Project 2.1 Release (codename "krogoth") from the prior release.
>  
>  .. _migration-2.1-variable-expansion-in-python-functions:
>  
> diff --git a/documentation/ref-manual/migration-2.2.rst b/documentation/ref-manual/migration-2.2.rst
> index 8b3c5d6..198181a 100644
> --- a/documentation/ref-manual/migration-2.2.rst
> +++ b/documentation/ref-manual/migration-2.2.rst
> @@ -1,8 +1,8 @@
> -Moving to the Yocto Project 2.2 Release
> -=======================================
> +Moving to the Yocto Project 2.2 Release (morty)
> +===============================================
>  
>  This section provides migration information for moving to the Yocto
> -Project 2.2 Release from the prior release.
> +Project 2.2 Release (codename "morty") from the prior release.
>  
>  .. _migration-2.2-minimum-kernel-version:
>  
> diff --git a/documentation/ref-manual/migration-2.3.rst b/documentation/ref-manual/migration-2.3.rst
> index 04b11da..0541eb3 100644
> --- a/documentation/ref-manual/migration-2.3.rst
> +++ b/documentation/ref-manual/migration-2.3.rst
> @@ -1,8 +1,8 @@
> -Moving to the Yocto Project 2.3 Release
> -=======================================
> +Moving to the Yocto Project 2.3 Release (pyro)
> +==============================================
>  
>  This section provides migration information for moving to the Yocto
> -Project 2.3 Release from the prior release.
> +Project 2.3 Release (codename "pyro") from the prior release.
>  
>  .. _migration-2.3-recipe-specific-sysroots:
>  
> diff --git a/documentation/ref-manual/migration-2.4.rst b/documentation/ref-manual/migration-2.4.rst
> index 260b320..2ba17e0 100644
> --- a/documentation/ref-manual/migration-2.4.rst
> +++ b/documentation/ref-manual/migration-2.4.rst
> @@ -1,8 +1,8 @@
> -Moving to the Yocto Project 2.4 Release
> -=======================================
> +Moving to the Yocto Project 2.4 Release (rocko)
> +===============================================
>  
>  This section provides migration information for moving to the Yocto
> -Project 2.4 Release from the prior release.
> +Project 2.4 Release (codename "rocko") from the prior release.
>  
>  .. _migration-2.4-memory-resident-mode:
>  
> diff --git a/documentation/ref-manual/migration-2.5.rst b/documentation/ref-manual/migration-2.5.rst
> index 9f45ffc..9ef4b55 100644
> --- a/documentation/ref-manual/migration-2.5.rst
> +++ b/documentation/ref-manual/migration-2.5.rst
> @@ -1,8 +1,8 @@
> -Moving to the Yocto Project 2.5 Release
> -=======================================
> +Moving to the Yocto Project 2.5 Release (sumo)
> +==============================================
>  
>  This section provides migration information for moving to the Yocto
> -Project 2.5 Release from the prior release.
> +Project 2.5 Release (codename "sumo") from the prior release.
>  
>  .. _migration-2.5-packaging-changes:
>  
> diff --git a/documentation/ref-manual/migration-2.6.rst b/documentation/ref-manual/migration-2.6.rst
> index 823d3cb..aeac509 100644
> --- a/documentation/ref-manual/migration-2.6.rst
> +++ b/documentation/ref-manual/migration-2.6.rst
> @@ -1,8 +1,8 @@
> -Moving to the Yocto Project 2.6 Release
> -=======================================
> +Moving to the Yocto Project 2.6 Release (thud)
> +==============================================
>  
>  This section provides migration information for moving to the Yocto
> -Project 2.6 Release from the prior release.
> +Project 2.6 Release (codename "thud") from the prior release.
>  
>  .. _migration-2.6-gcc-changes:
>  
> diff --git a/documentation/ref-manual/migration-2.7.rst b/documentation/ref-manual/migration-2.7.rst
> index 5af5947..1be4d5d 100644
> --- a/documentation/ref-manual/migration-2.7.rst
> +++ b/documentation/ref-manual/migration-2.7.rst
> @@ -1,8 +1,8 @@
> -Moving to the Yocto Project 2.7 Release
> -=======================================
> +Moving to the Yocto Project 2.7 Release (warrior)
> +=================================================
>  
>  This section provides migration information for moving to the Yocto
> -Project 2.7 Release from the prior release.
> +Project 2.7 Release (codename "warrior") from the prior release.
>  
>  .. _migration-2.7-bitbake-changes:
>  
> diff --git a/documentation/ref-manual/migration-3.0.rst b/documentation/ref-manual/migration-3.0.rst
> index 7ef2742..f3d20e2 100644
> --- a/documentation/ref-manual/migration-3.0.rst
> +++ b/documentation/ref-manual/migration-3.0.rst
> @@ -1,8 +1,8 @@
> -Moving to the Yocto Project 3.0 Release
> -=======================================
> +Moving to the Yocto Project 3.0 Release (zeus)
> +==============================================
>  
>  This section provides migration information for moving to the Yocto
> -Project 3.0 Release from the prior release.
> +Project 3.0 Release (codename "zeus") from the prior release.
>  
>  .. _migration-3.0-init-system-selection:
>  
> diff --git a/documentation/ref-manual/migration-3.1.rst b/documentation/ref-manual/migration-3.1.rst
> index 4fcd249..84d3250 100644
> --- a/documentation/ref-manual/migration-3.1.rst
> +++ b/documentation/ref-manual/migration-3.1.rst
> @@ -1,8 +1,8 @@
> -Moving to the Yocto Project 3.1 Release
> -=======================================
> +Moving to the Yocto Project 3.1 Release (dunfell)
> +=================================================
>  
>  This section provides migration information for moving to the Yocto
> -Project 3.1 Release from the prior release.
> +Project 3.1 Release (codename "dunfell") from the prior release.
>  
>  .. _migration-3.1-minimum-system-requirements:
>  
> diff --git a/documentation/ref-manual/migration-3.2.rst b/documentation/ref-manual/migration-3.2.rst
> index cca8124..39743af 100644
> --- a/documentation/ref-manual/migration-3.2.rst
> +++ b/documentation/ref-manual/migration-3.2.rst
> @@ -1,8 +1,8 @@
> -Moving to the Yocto Project 3.2 Release
> -=======================================
> +Moving to the Yocto Project 3.2 Release (gatesgarth)
> +====================================================
>  
>  This section provides migration information for moving to the Yocto
> -Project 3.2 Release from the prior release.
> +Project 3.2 Release (codename "gatesgarth") from the prior release.
>  
>  .. _migration-3.2-minimum-system-requirements:
>  
> diff --git a/documentation/ref-manual/migration-3.3.rst b/documentation/ref-manual/migration-3.3.rst
> index 8dfbe7f..ff010fd 100644
> --- a/documentation/ref-manual/migration-3.3.rst
> +++ b/documentation/ref-manual/migration-3.3.rst
> @@ -1,8 +1,8 @@
> -Moving to the Yocto Project 3.3 Release
> -=======================================
> +Moving to the Yocto Project 3.3 Release (hardknott)
> +===================================================
>  
>  This section provides migration information for moving to the Yocto
> -Project 3.3 Release from the prior release.
> +Project 3.3 Release (codename "hardknott") from the prior release.
>  
>  
>  .. _migration-3.3-minimum-system-requirements:
> -- 
> 1.8.3.1
> 

> 
> 
> 

Re: [docs] [PATCH 09/13] ref-manual: add FIT_KERNEL_COMP_ALG*

[Robert P. J. Day]

On Wed, 14 Apr 2021, Quentin Schulz wrote:

> Hi Paul,
>
> On Tue, Apr 13, 2021 at 05:19:50PM -0700, Paul Eggleton wrote:
> > From: Paul Eggleton <paul.eggleton@microsoft.com>
> >
> > Add FIT_KERNEL_COMP_ALG and FIT_KERNEL_COMP_ALG_EXTENSION. Examining
> > OE-Core commit 5c72105e2973e613b5c0f0e6310ffdea6e56c6c7 and the
> > associated code, these do not enable arbitrary selection of compression
> > algorithm - only disabling compression - so document them accordingly.
> >
> > Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
> > ---
> >  documentation/ref-manual/variables.rst | 11 +++++++++++
> >  1 file changed, 11 insertions(+)
> >
> > diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> > index 3b76dbc..f010cd7 100644
> > --- a/documentation/ref-manual/variables.rst
> > +++ b/documentation/ref-manual/variables.rst
> > @@ -2580,6 +2580,17 @@ system and gives an overview of their function and contents.
> >     :term:`FIT_HASH_ALG`
> >        Specifies the hash algorithm used in creating the FIT Image. For e.g. sha256.
> >
> > +   :term:`FIT_KERNEL_COMP_ALG`
> > +      Compression algorithm to use for the kernel image inside the fitImage.
> > +      At present, the only supported values are "gzip" (default) or "none",
> > +      which allows disabling of compression if it would otherwise be enabled.
>
> I'm not a native speaker and I'm struggling to understand that last line,
> would it be possible for you to rephrase please?

  i would just drop the second half of that second sentence -- the
first part says all that needs to be said:

  Compression algorithm to use for the kernel image inside the
  fitImage; at present, the only supported values are "gzip" (default)
  or "none".

i would pick nits with the varieties of the phrase "fitImage";
regardless of how it's used as a variable, i believe the proper
reference is "FIT image", which is how it should appear in the above,
methinks.

> > +      If you set this you will also need to set :term:`FIT_KERNEL_COMP_ALG_EXTENSION`.
> > +
> > +   :term:`FIT_KERNEL_COMP_ALG_EXTENSION`
> > +      File extension corresponding to :term:`FIT_KERNEL_COMP_ALG`. The default
> > +      value is ".gz"; if you set ``FIT_KERNEL_COMP_ALG`` to "none" then
>
> s/``FIT_KERNEL_COMP_ALG``/:term:`FIT_KERNEL_COMP_ALG`/

  since the first occurrence is already term'ed, the remaining
occurrences in that entry don't need to be, isn't that the standard
that's being used?

rday

Re: [docs] [PATCH 08/13] ref-manual: add passwd-expire to EXTRA_USERS_PARAMS

[Robert P. J. Day]

[-- Attachment #1: Type: text/plain, Size: 1898 bytes --]

On Wed, 14 Apr 2021, Nicolas Dechesne wrote:

> On Wed, Apr 14, 2021 at 10:13 AM Quentin Schulz <quentin.schulz@streamunlimited.com>
> wrote:
>       Hi Paul,
>
>       On Tue, Apr 13, 2021 at 05:19:49PM -0700, Paul Eggleton wrote:
>       > From: Paul Eggleton <paul.eggleton@microsoft.com>
>       >
>       > Add a reference to the recently added passwd-expire command in
>       > EXTRA_USERS_PARAMS.
>       >
>       > Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
>       > ---
>       >  documentation/ref-manual/variables.rst | 11 +++++++++++
>       >  1 file changed, 11 insertions(+)
>       >
>       > diff --git a/documentation/ref-manual/variables.rst
>       b/documentation/ref-manual/variables.rst
>       > index 2e3cc22..3b76dbc 100644
>       > --- a/documentation/ref-manual/variables.rst
>       > +++ b/documentation/ref-manual/variables.rst
>       > @@ -2293,6 +2293,17 @@ system and gives an overview of their function and
>       contents.
>       >           # usermod -s /bin/sh tester; \
>       >           # "
>       > 
>       > +      Additionally there is a special ``passwd-expire`` command that will
>       > +      cause the password for a user to be expired and thus force changing
>       it
>       > +      on first login, for example: ::
>       > +
>
>       IIRC, :: will behave the same as : ::, so please use the former (trying to
>       have consistency across all docs, though we're far from it now :|, but
>       this change is something we want).
>
>       Pinging @Nicolas just for confirmation :)
>
>
> Yes, agreed. There was a patch floating around to convert all
> instances of : :: into ::, not sure if it was merged or dropped..

  i recall sending such a patch a while back, but for whatever reason,
it did not apply cleanly so it was shelved.

rday

Re: [docs] [PATCH 09/13] ref-manual: add FIT_KERNEL_COMP_ALG*

[Quentin Schulz]

On Wed, Apr 14, 2021 at 04:35:19AM -0400, Robert P. J. Day wrote:
> On Wed, 14 Apr 2021, Quentin Schulz wrote:
> 
> > Hi Paul,
> >
> > On Tue, Apr 13, 2021 at 05:19:50PM -0700, Paul Eggleton wrote:
> > > From: Paul Eggleton <paul.eggleton@microsoft.com>
> > >
> > > Add FIT_KERNEL_COMP_ALG and FIT_KERNEL_COMP_ALG_EXTENSION. Examining
> > > OE-Core commit 5c72105e2973e613b5c0f0e6310ffdea6e56c6c7 and the
> > > associated code, these do not enable arbitrary selection of compression
> > > algorithm - only disabling compression - so document them accordingly.
> > >
> > > Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
> > > ---
> > >  documentation/ref-manual/variables.rst | 11 +++++++++++
> > >  1 file changed, 11 insertions(+)
> > >
> > > diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> > > index 3b76dbc..f010cd7 100644
> > > --- a/documentation/ref-manual/variables.rst
> > > +++ b/documentation/ref-manual/variables.rst
> > > @@ -2580,6 +2580,17 @@ system and gives an overview of their function and contents.
> > >     :term:`FIT_HASH_ALG`
> > >        Specifies the hash algorithm used in creating the FIT Image. For e.g. sha256.
> > >
> > > +   :term:`FIT_KERNEL_COMP_ALG`
> > > +      Compression algorithm to use for the kernel image inside the fitImage.
> > > +      At present, the only supported values are "gzip" (default) or "none",
> > > +      which allows disabling of compression if it would otherwise be enabled.
> >
> > I'm not a native speaker and I'm struggling to understand that last line,
> > would it be possible for you to rephrase please?
> 
>   i would just drop the second half of that second sentence -- the
> first part says all that needs to be said:
> 
>   Compression algorithm to use for the kernel image inside the
>   fitImage; at present, the only supported values are "gzip" (default)
>   or "none".
> 
> i would pick nits with the varieties of the phrase "fitImage";
> regardless of how it's used as a variable, i believe the proper
> reference is "FIT image", which is how it should appear in the above,
> methinks.
> 
> > > +      If you set this you will also need to set :term:`FIT_KERNEL_COMP_ALG_EXTENSION`.
> > > +
> > > +   :term:`FIT_KERNEL_COMP_ALG_EXTENSION`
> > > +      File extension corresponding to :term:`FIT_KERNEL_COMP_ALG`. The default
> > > +      value is ".gz"; if you set ``FIT_KERNEL_COMP_ALG`` to "none" then
> >
> > s/``FIT_KERNEL_COMP_ALG``/:term:`FIT_KERNEL_COMP_ALG`/
> 
>   since the first occurrence is already term'ed, the remaining
> occurrences in that entry don't need to be, isn't that the standard
> that's being used?
> 

We're planning to have all variable references to be :term:'ed
eventually, so better not add more to change later on :)

Quentin

Re: [docs] [PATCH 09/13] ref-manual: add FIT_KERNEL_COMP_ALG*

[Robert P. J. Day]

On Wed, 14 Apr 2021, Quentin Schulz wrote:

... snip ...

> We're planning to have all variable references to be :term:'ed
> eventually, so better not add more to change later on :)

  ah, i was unaware of that. carry on, then.

rday

Re: [docs] [PATCH 12/13] ref-manual: add migration section for 3.3 release

[Paul Eggleton]

Hi Quentin

Thanks for the review!

On Wednesday, 14 April 2021 20:26:03 NZST Quentin Schulz wrote:
> On Tue, Apr 13, 2021 at 05:19:53PM -0700, Paul Eggleton wrote:
> > +BitBake changes
> > +---------------
> > +
> > +- BitBake is now configured to use a default ``umask`` of ``022`` for all
> > tasks +  (specified via a new ``BB_DEFAULT_UMASK`` variable). If needed,
> > ``umask`` can
> s/``BB_DEFAULT_UMASK``/:term:`BB_DEFAULT_UMASK`/
> 
> IIRC, this works fine even for bitbake terms (might need some tweaking
> if it does not work but I know we use :term: for some bitbake variables
> from bitbake's docs).

Wow, that does work but I didn't imagine that it would. Any idea how it 
resolves those references given that doc is not in this tree?
 
> > +- ``iproute2``: split ip binary to its own package
> 
> s/ip/``ip``/

Well spotted! Fixed.
 
> > +- The default poky :term:`DISTRO_VERSION` value now uses the core
> > metadata's +  git hash (i.e. :term:`METADATA_REVISION`) rather than the
> > date (i.e. +  :term:`DATE`) to reduce one small source of
> > non-reproducibility. You can +  of course specify your own
> > ``DISTRO_VERSION`` value as desired
> 
> s/``DISTRO_VERSION``/:term:`DISTRO_VERSION`/

Fixed.
 
> > +  (particularly if you create your own custom distro configuration).
> > +- The :ref:`ccache <ref-classes-ccache>` class now uses ``ccache`` from
> > the +  build host rather than building ``ccache-native`` (due to circular
> > +  dependencies in ccache 4.0 that are impractical to resolve otherwise),
> > so +  if you enable it you will now need to have ``ccache`` installed on
> > your +  host system.
> 
> Will a warning be shown if ccache is not installed on the host or does
> it silently fail to use ccache?

Good question, but on further digging I found the corresponding code change 
actually got reverted and I had missed that in my earlier sweep. Just as well 
you asked about it :)

I've incorporated all of your other feedback and will send a new series 
imminently.

Cheers
Paul

Re: [docs] [PATCH 12/13] ref-manual: add migration section for 3.3 release

[Quentin Schulz]

Hi Paul,

On Thu, Apr 15, 2021 at 09:52:31PM +1200, Paul Eggleton wrote:
> Hi Quentin
> 
> Thanks for the review!
> 
> On Wednesday, 14 April 2021 20:26:03 NZST Quentin Schulz wrote:
> > On Tue, Apr 13, 2021 at 05:19:53PM -0700, Paul Eggleton wrote:
> > > +BitBake changes
> > > +---------------
> > > +
> > > +- BitBake is now configured to use a default ``umask`` of ``022`` for all
> > > tasks +  (specified via a new ``BB_DEFAULT_UMASK`` variable). If needed,
> > > ``umask`` can
> > s/``BB_DEFAULT_UMASK``/:term:`BB_DEFAULT_UMASK`/
> > 
> > IIRC, this works fine even for bitbake terms (might need some tweaking
> > if it does not work but I know we use :term: for some bitbake variables
> > from bitbake's docs).
> 
> Wow, that does work but I didn't imagine that it would. Any idea how it 
> resolves those references given that doc is not in this tree?
>  

How internally it works? No idea :)

But the few lines here are what makes it work:
https://git.yoctoproject.org/cgit/cgit.cgi/yocto-docs/tree/documentation/conf.py#n90

Nicolas and/or other peoples involved in the migration might be able to
tell you more, I'm not :/

"it works for me" is enough to me right now :p

[...]

> > > +  (particularly if you create your own custom distro configuration).
> > > +- The :ref:`ccache <ref-classes-ccache>` class now uses ``ccache`` from
> > > the +  build host rather than building ``ccache-native`` (due to circular
> > > +  dependencies in ccache 4.0 that are impractical to resolve otherwise),
> > > so +  if you enable it you will now need to have ``ccache`` installed on
> > > your +  host system.
> > 
> > Will a warning be shown if ccache is not installed on the host or does
> > it silently fail to use ccache?
> 
> Good question, but on further digging I found the corresponding code change 
> actually got reverted and I had missed that in my earlier sweep. Just as well 
> you asked about it :)
> 

:)

Cheers,
Quentin

Re: [docs] [PATCH 09/13] ref-manual: add FIT_KERNEL_COMP_ALG*

[Paul Eggleton]

Hi Robert

On Wednesday, 14 April 2021 20:35:19 NZST Robert P. J. Day wrote:
> On Wed, 14 Apr 2021, Quentin Schulz wrote:
> > On Tue, Apr 13, 2021 at 05:19:50PM -0700, Paul Eggleton wrote:
> > > --- a/documentation/ref-manual/variables.rst
> > > +++ b/documentation/ref-manual/variables.rst
> > > @@ -2580,6 +2580,17 @@ system and gives an overview of their function
> > > and contents.> > 
> > >     :term:`FIT_HASH_ALG`
> > >     :
> > >        Specifies the hash algorithm used in creating the FIT Image. For
> > >        e.g. sha256.> > 
> > > +   :term:`FIT_KERNEL_COMP_ALG`
> > > +      Compression algorithm to use for the kernel image inside the
> > > fitImage. +      At present, the only supported values are "gzip"
> > > (default) or "none", +      which allows disabling of compression if it
> > > would otherwise be enabled.> 
> > I'm not a native speaker and I'm struggling to understand that last line,
> > would it be possible for you to rephrase please?
> 
>   i would just drop the second half of that second sentence -- the
> first part says all that needs to be said:
> 
>   Compression algorithm to use for the kernel image inside the
>   fitImage; at present, the only supported values are "gzip" (default)
>   or "none".

Sounds reasonable, I've done exactly this. I also adjusted the text to remove 
mention of setting  FIT_KERNEL_COMP_ALG_EXTENSION if FIT_KERNEL_COMP_ALG is 
set to "none" (upon closer inspection that isn't necessary based on how the 
code behaves).

> i would pick nits with the varieties of the phrase "fitImage";
> regardless of how it's used as a variable, i believe the proper
> reference is "FIT image", which is how it should appear in the above,
> methinks.

Yep I fixed this as well. We're not consistent with this in the existing text, 
I haven't fixed that so we probably should in future.

Thanks,
Paul

Re: [docs] [PATCH 12/13] ref-manual: add migration section for 3.3 release

[Nicolas Dechesne]

[-- Attachment #1: Type: text/plain, Size: 3901 bytes --]

On Thu, Apr 15, 2021 at 11:59 AM Quentin Schulz <
quentin.schulz@streamunlimited.com> wrote:

> Hi Paul,
>
> On Thu, Apr 15, 2021 at 09:52:31PM +1200, Paul Eggleton wrote:
> > Hi Quentin
> >
> > Thanks for the review!
> >
> > On Wednesday, 14 April 2021 20:26:03 NZST Quentin Schulz wrote:
> > > On Tue, Apr 13, 2021 at 05:19:53PM -0700, Paul Eggleton wrote:
> > > > +BitBake changes
> > > > +---------------
> > > > +
> > > > +- BitBake is now configured to use a default ``umask`` of ``022``
> for all
> > > > tasks +  (specified via a new ``BB_DEFAULT_UMASK`` variable). If
> needed,
> > > > ``umask`` can
> > > s/``BB_DEFAULT_UMASK``/:term:`BB_DEFAULT_UMASK`/
> > >
> > > IIRC, this works fine even for bitbake terms (might need some tweaking
> > > if it does not work but I know we use :term: for some bitbake variables
> > > from bitbake's docs).
> >
> > Wow, that does work but I didn't imagine that it would. Any idea how it
> > resolves those references given that doc is not in this tree?
> >
>
> How internally it works? No idea :)
>

It is interesting... I would not have expected that to work ;)


>
> But the few lines here are what makes it work:
>
> https://git.yoctoproject.org/cgit/cgit.cgi/yocto-docs/tree/documentation/conf.py#n90


So, this is correct we use the intersphinx extension to link YP and bitbake
docs which are indeed 2 different sphinx projects. When we build the YP
docs, it will first download the bitbake sphinx 'index, e.g. you can see
that in the log when building YP docs:

loading intersphinx inventory from
https://docs.yoctoproject.org/bitbake/objects.inv...

So now sphinx knows about all the :ref:, :doc:, :term:, ... defined in
bitbake, so we can use them to create cross references. More on that here:
https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html

A nice debug tip is to run:
python -msphinx.ext.intersphinx
https://docs.yoctoproject.org/bitbake/objects.inv

which shows all the bitbake references that can be used from YP docs.


>
>
> Nicolas and/or other peoples involved in the migration might be able to
> tell you more, I'm not :/
>
> "it works for me" is enough to me right now :p
>

Yes, it does! I never realized that it would, and I have always
explicitely used the intersphinx prefix, e.g. :term:`bibtake:BB_XXX`. But
reading the doc more carefully, it states that you can use the 'prefix' to
force the lookup to be done in the specific intersphinx. But if the
reference is 'unique' then the prefix is not required. And it works for
:ref: as well.. I tried with:
:ref:`Fetchers <bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`

and it worked fine.. that's cool, because that means we should be able to
remove some extraneous bitbake: prefix in few places.

As for :term:`BB_DEFAULT_UMASK` it works because this 'term' is not define
in the YP reference manual terms. If you add it in YP doc then the link
will use the local term instead of bitbake, which makes sense I suppose.


> [...]
>
> > > > +  (particularly if you create your own custom distro configuration).
> > > > +- The :ref:`ccache <ref-classes-ccache>` class now uses ``ccache``
> from
> > > > the +  build host rather than building ``ccache-native`` (due to
> circular
> > > > +  dependencies in ccache 4.0 that are impractical to resolve
> otherwise),
> > > > so +  if you enable it you will now need to have ``ccache``
> installed on
> > > > your +  host system.
> > >
> > > Will a warning be shown if ccache is not installed on the host or does
> > > it silently fail to use ccache?
> >
> > Good question, but on further digging I found the corresponding code
> change
> > actually got reverted and I had missed that in my earlier sweep. Just as
> well
> > you asked about it :)
> >
>
> :)
>
> Cheers,
> Quentin
>
> 
>
>

[-- Attachment #2: Type: text/html, Size: 5603 bytes --]

Re: [docs] [PATCH 00/13] Documentation updates for 3.3

[Michael Opdenacker]

Hi Paul,

On 4/14/21 2:19 AM, Paul Eggleton wrote:
> The migration guide for 3.3, plus some missing related changes and a few
> cleanups. Let me know if I missed anything.
>
>
> The following changes since commit 4f7f451df266a307b34bf145b29291ca85eb882f:
>
>   docs: add a top level page for bitbake documentation (2021-04-09 09:00:53 +0200)
>
> are available in the git repository at:
>
>   git://git.yoctoproject.org/poky-contrib paule/migration-3.3
>   http://git.yoctoproject.org/cgit.cgi/poky-contrib/log/?h=paule/migration-3.3


Thanks, the changes look good to me. I checked that indeed you took the
feedback into account.

I merged them in yocto-docs' master-next.

Many thanks!

Cheers,

Michael.

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

Re: [docs] [PATCH 00/13] Documentation updates for 3.3

[Quentin Schulz]

Hi Michael,

On Thu, Apr 15, 2021 at 03:54:28PM +0200, Michael Opdenacker wrote:
> Hi Paul,
> 
> On 4/14/21 2:19 AM, Paul Eggleton wrote:
> > The migration guide for 3.3, plus some missing related changes and a few
> > cleanups. Let me know if I missed anything.
> >
> >
> > The following changes since commit 4f7f451df266a307b34bf145b29291ca85eb882f:
> >
> >   docs: add a top level page for bitbake documentation (2021-04-09 09:00:53 +0200)
> >
> > are available in the git repository at:
> >
> >   git://git.yoctoproject.org/poky-contrib paule/migration-3.3
> >   http://git.yoctoproject.org/cgit.cgi/poky-contrib/log/?h=paule/migration-3.3
> 
> 
> Thanks, the changes look good to me. I checked that indeed you took the
> feedback into account.
> 
> I merged them in yocto-docs' master-next.
> 

You answered on the v1 thread. I'm here just to make sure you took the
v2?

Thanks,
Quentin

Re: [docs] [PATCH 00/13] Documentation updates for 3.3

[Michael Opdenacker]

On 4/15/21 4:00 PM, Quentin Schulz wrote:
> Hi Michael,
>
> On Thu, Apr 15, 2021 at 03:54:28PM +0200, Michael Opdenacker wrote:
>> Hi Paul,
>>
>> On 4/14/21 2:19 AM, Paul Eggleton wrote:
>>> The migration guide for 3.3, plus some missing related changes and a few
>>> cleanups. Let me know if I missed anything.
>>>
>>>
>>> The following changes since commit 4f7f451df266a307b34bf145b29291ca85eb882f:
>>>
>>>   docs: add a top level page for bitbake documentation (2021-04-09 09:00:53 +0200)
>>>
>>> are available in the git repository at:
>>>
>>>   git://git.yoctoproject.org/poky-contrib paule/migration-3.3
>>>   http://git.yoctoproject.org/cgit.cgi/poky-contrib/log/?h=paule/migration-3.3
>>
>> Thanks, the changes look good to me. I checked that indeed you took the
>> feedback into account.
>>
>> I merged them in yocto-docs' master-next.
>>
> You answered on the v1 thread. I'm here just to make sure you took the
> v2?


Oops, yes, indeed, I took the v2, apologies! I was comparing both
threads, to check that the comments had been taken into account.

Thanks for asking, and above all many thanks for your reviews!

http://git.yoctoproject.org/cgit/cgit.cgi/yocto-docs/log/?h=master-next

Michael.

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

Re: [docs] [PATCH 12/13] ref-manual: add migration section for 3.3 release

[Quentin Schulz]

On Thu, Apr 15, 2021 at 12:25:55PM +0200, Nicolas Dechesne wrote:
> On Thu, Apr 15, 2021 at 11:59 AM Quentin Schulz <
> quentin.schulz@streamunlimited.com> wrote:
> > On Thu, Apr 15, 2021 at 09:52:31PM +1200, Paul Eggleton wrote:
> > > On Wednesday, 14 April 2021 20:26:03 NZST Quentin Schulz wrote:
> > > > On Tue, Apr 13, 2021 at 05:19:53PM -0700, Paul Eggleton wrote:
> > > > > +BitBake changes
> > > > > +---------------
> > > > > +
> > > > > +- BitBake is now configured to use a default ``umask`` of ``022``
> > for all
> > > > > tasks +  (specified via a new ``BB_DEFAULT_UMASK`` variable). If
> > needed,
> > > > > ``umask`` can
> > > > s/``BB_DEFAULT_UMASK``/:term:`BB_DEFAULT_UMASK`/
> > > >
> > > > IIRC, this works fine even for bitbake terms (might need some tweaking
> > > > if it does not work but I know we use :term: for some bitbake variables
> > > > from bitbake's docs).
> > >
> > > Wow, that does work but I didn't imagine that it would. Any idea how it
> > > resolves those references given that doc is not in this tree?
> > >
> >
> > How internally it works? No idea :)
> >
> 
> It is interesting... I would not have expected that to work ;)
> 
> 
> >
> > But the few lines here are what makes it work:
> >
> > https://git.yoctoproject.org/cgit/cgit.cgi/yocto-docs/tree/documentation/conf.py#n90
> 
> 
> So, this is correct we use the intersphinx extension to link YP and bitbake
> docs which are indeed 2 different sphinx projects. When we build the YP
> docs, it will first download the bitbake sphinx 'index, e.g. you can see
> that in the log when building YP docs:
> 
> loading intersphinx inventory from
> https://docs.yoctoproject.org/bitbake/objects.inv...
> 
> So now sphinx knows about all the :ref:, :doc:, :term:, ... defined in
> bitbake, so we can use them to create cross references. More on that here:
> https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
> 
> A nice debug tip is to run:
> python -msphinx.ext.intersphinx
> https://docs.yoctoproject.org/bitbake/objects.inv
> 
> which shows all the bitbake references that can be used from YP docs.
> 
> 
> >
> >
> > Nicolas and/or other peoples involved in the migration might be able to
> > tell you more, I'm not :/
> >
> > "it works for me" is enough to me right now :p
> >
> 
> Yes, it does! I never realized that it would, and I have always
> explicitely used the intersphinx prefix, e.g. :term:`bibtake:BB_XXX`. But
> reading the doc more carefully, it states that you can use the 'prefix' to
> force the lookup to be done in the specific intersphinx. But if the
> reference is 'unique' then the prefix is not required. And it works for
> :ref: as well.. I tried with:
> :ref:`Fetchers <bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`
> 
> and it worked fine.. that's cool, because that means we should be able to
> remove some extraneous bitbake: prefix in few places.
> 
> As for :term:`BB_DEFAULT_UMASK` it works because this 'term' is not define
> in the YP reference manual terms. If you add it in YP doc then the link
> will use the local term instead of bitbake, which makes sense I suppose.
> 

I think so? I could imagine some bitbake variables to be better explained in
the context of their use in the Yocto Project.

We have to be careful with :ref: though, I wouldn't want links to point
to the incorrect doc if the reference appears in both documentations?
Especially since Sphinx wouldn't detect this as an error, since the
:ref: would be valid in both cases. I'm pretty sure it's very unlikely
to happen, but do we want to risk it :) ?

Cheers,
Quentin
-- 
StreamUnlimited Engineering GmbH
High Tech Campus Vienna, Gutheil-Schoder-Gasse 10, 1100 Vienna, Austria
Fax: +43 1 667 20 02 4401
quentin.schulz@streamunlimited.com, www.streamunlimited.com

Re: [docs] [PATCH 12/13] ref-manual: add migration section for 3.3 release

[Michael Opdenacker]

On 4/15/21 12:25 PM, Nicolas Dechesne wrote:
>
>
> and it worked fine.. that's cool, because that means we should be able
> to remove some extraneous bitbake: prefix in few places.


Indeed! I'll propose a patch doing this.

Thanks,

Michael.

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

Re: [docs] [PATCH 08/13] ref-manual: add passwd-expire to EXTRA_USERS_PARAMS

[Michael Opdenacker]

Hi,

On 4/14/21 10:36 AM, Robert P. J. Day wrote:
>   i recall sending such a patch a while back, but for whatever reason,
> it did not apply cleanly so it was shelved.


I'll be happy to make a new version, thanks!

Michael.

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

Re: [docs] [PATCH 12/13] ref-manual: add migration section for 3.3 release

[Nicolas Dechesne]

[-- Attachment #1: Type: text/plain, Size: 4739 bytes --]

On Thu, Apr 15, 2021 at 4:07 PM Quentin Schulz <
quentin.schulz@streamunlimited.com> wrote:

> On Thu, Apr 15, 2021 at 12:25:55PM +0200, Nicolas Dechesne wrote:
> > On Thu, Apr 15, 2021 at 11:59 AM Quentin Schulz <
> > quentin.schulz@streamunlimited.com> wrote:
> > > On Thu, Apr 15, 2021 at 09:52:31PM +1200, Paul Eggleton wrote:
> > > > On Wednesday, 14 April 2021 20:26:03 NZST Quentin Schulz wrote:
> > > > > On Tue, Apr 13, 2021 at 05:19:53PM -0700, Paul Eggleton wrote:
> > > > > > +BitBake changes
> > > > > > +---------------
> > > > > > +
> > > > > > +- BitBake is now configured to use a default ``umask`` of
> ``022``
> > > for all
> > > > > > tasks +  (specified via a new ``BB_DEFAULT_UMASK`` variable). If
> > > needed,
> > > > > > ``umask`` can
> > > > > s/``BB_DEFAULT_UMASK``/:term:`BB_DEFAULT_UMASK`/
> > > > >
> > > > > IIRC, this works fine even for bitbake terms (might need some
> tweaking
> > > > > if it does not work but I know we use :term: for some bitbake
> variables
> > > > > from bitbake's docs).
> > > >
> > > > Wow, that does work but I didn't imagine that it would. Any idea how
> it
> > > > resolves those references given that doc is not in this tree?
> > > >
> > >
> > > How internally it works? No idea :)
> > >
> >
> > It is interesting... I would not have expected that to work ;)
> >
> >
> > >
> > > But the few lines here are what makes it work:
> > >
> > >
> https://git.yoctoproject.org/cgit/cgit.cgi/yocto-docs/tree/documentation/conf.py#n90
> >
> >
> > So, this is correct we use the intersphinx extension to link YP and
> bitbake
> > docs which are indeed 2 different sphinx projects. When we build the YP
> > docs, it will first download the bitbake sphinx 'index, e.g. you can see
> > that in the log when building YP docs:
> >
> > loading intersphinx inventory from
> > https://docs.yoctoproject.org/bitbake/objects.inv...
> >
> > So now sphinx knows about all the :ref:, :doc:, :term:, ... defined in
> > bitbake, so we can use them to create cross references. More on that
> here:
> > https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
> >
> > A nice debug tip is to run:
> > python -msphinx.ext.intersphinx
> > https://docs.yoctoproject.org/bitbake/objects.inv
> >
> > which shows all the bitbake references that can be used from YP docs.
> >
> >
> > >
> > >
> > > Nicolas and/or other peoples involved in the migration might be able to
> > > tell you more, I'm not :/
> > >
> > > "it works for me" is enough to me right now :p
> > >
> >
> > Yes, it does! I never realized that it would, and I have always
> > explicitely used the intersphinx prefix, e.g. :term:`bibtake:BB_XXX`. But
> > reading the doc more carefully, it states that you can use the 'prefix'
> to
> > force the lookup to be done in the specific intersphinx. But if the
> > reference is 'unique' then the prefix is not required. And it works for
> > :ref: as well.. I tried with:
> > :ref:`Fetchers
> <bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`
> >
> > and it worked fine.. that's cool, because that means we should be able to
> > remove some extraneous bitbake: prefix in few places.
> >
> > As for :term:`BB_DEFAULT_UMASK` it works because this 'term' is not
> define
> > in the YP reference manual terms. If you add it in YP doc then the link
> > will use the local term instead of bitbake, which makes sense I suppose.
> >
>
> I think so? I could imagine some bitbake variables to be better explained
> in
> the context of their use in the Yocto Project.
>
> We have to be careful with :ref: though, I wouldn't want links to point
> to the incorrect doc if the reference appears in both documentations?
> Especially since Sphinx wouldn't detect this as an error, since the
> :ref: would be valid in both cases. I'm pretty sure it's very unlikely
> to happen, but do we want to risk it :) ?
>

You might be right.. perhaps being explicit is better.. to avoid any issue
with disambiguation...
the bitbake: prefix bothers me a bit (too long), so perhaps we could change
it to bb: and enforce it everywhere it's needed.

I think i had a patch that renamed folder and files in bitbake docs (like
we did for yp-docs already), that would also help shorten all references..
e.g.

:ref:`Fetchers <bb:user-manual/fetching:fetchers>`
looks much better than
:ref:`Fetchers <bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`


>
> Cheers,
> Quentin
> --
> StreamUnlimited Engineering GmbH
> High Tech Campus Vienna, Gutheil-Schoder-Gasse 10, 1100 Vienna, Austria
> Fax: +43 1 667 20 02 4401
> quentin.schulz@streamunlimited.com, www.streamunlimited.com
>

[-- Attachment #2: Type: text/html, Size: 6675 bytes --]