diff --git a/poky/documentation/ref-manual/TODO b/poky/documentation/ref-manual/TODO
index ee0db97..0510f54 100644
--- a/poky/documentation/ref-manual/TODO
+++ b/poky/documentation/ref-manual/TODO
@@ -1,10 +1,10 @@
 Handbook Todo List:
 
-  * Document adding a new IMAGE_FEATURE to the customising images section 
+  * Document adding a new IMAGE_FEATURE to the customising images section
   * Add instructions about using zaurus/openmoko emulation
   * Add component overview/block diagrams
-  * Software Deevelopment intro should mention its software development for 
-    intended target and could be a different arch etc and thus special case. 
+  * Software Development intro should mention its software development for
+    intended target and could be a different arch etc and thus special case.
   * Expand insane.bbclass documentation to cover tests
   * Document remaining classes (see list in ref-classes)
   * Document formfactor
diff --git a/poky/documentation/ref-manual/classes.rst b/poky/documentation/ref-manual/classes.rst
index be112e0..52a50fa 100644
--- a/poky/documentation/ref-manual/classes.rst
+++ b/poky/documentation/ref-manual/classes.rst
@@ -501,29 +501,6 @@
 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 @@
    ``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``
@@ -1426,7 +1397,7 @@
 The boot script is specified in the ITS file as a text file containing
 U-boot commands. When using a boot script the user should configure the
 U-boot ``do_install`` task to copy the script to sysroot.
-So the script can be included in the the FIT image by the ``kernel-fitimage``
+So the script can be included in the FIT image by the ``kernel-fitimage``
 class. At run-time, U-boot CONFIG_BOOTCOMMAND define can be configured to
 load the boot script from the FIT image and executes it.
 
@@ -2138,13 +2109,13 @@
 ":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 @@
 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 @@
 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/poky/documentation/ref-manual/devtool-reference.rst b/poky/documentation/ref-manual/devtool-reference.rst
index 5075f0c..629aa2f 100644
--- a/poky/documentation/ref-manual/devtool-reference.rst
+++ b/poky/documentation/ref-manual/devtool-reference.rst
@@ -178,8 +178,8 @@
    $ devtool add jackson /home/user/sources/jackson
 
 If you add a recipe and the workspace layer does not exist, the command
-creates the layer and populates it as described in "`The Workspace Layer
-Structure <#devtool-the-workspace-layer-structure>`__" section.
+creates the layer and populates it as described in
+":ref:`devtool-the-workspace-layer-structure`" section.
 
 Running ``devtool add`` when the workspace layer exists causes the tool
 to add the recipe, append files, and source files into the existing
diff --git a/poky/documentation/ref-manual/faq.rst b/poky/documentation/ref-manual/faq.rst
index 34b26ee..64fdfdf 100644
--- a/poky/documentation/ref-manual/faq.rst
+++ b/poky/documentation/ref-manual/faq.rst
@@ -16,7 +16,7 @@
 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
@@ -449,7 +449,7 @@
 "/usr/bin" worked most of the time, but not for the recipe's ``-native``
 variant. For another example, permissions errors might be caused by a
 Makefile that ignores ``DESTDIR`` or uses a different name for that
-environment variable. Check the the build system to see if these kinds
+environment variable. Check the build system to see if these kinds
 of issues exist.
 
 **Q:** I'm adding a binary in a recipe but it's different in the image, what is
diff --git a/poky/documentation/ref-manual/kickstart.rst b/poky/documentation/ref-manual/kickstart.rst
index 472820f..b87cdc1 100644
--- a/poky/documentation/ref-manual/kickstart.rst
+++ b/poky/documentation/ref-manual/kickstart.rst
@@ -33,7 +33,7 @@
 following syntax:
 ::
 
-   part [mntpoint] 
+   part [mntpoint]
    partition [mntpoint]
 
 If you do not
@@ -55,7 +55,7 @@
 .. note::
 
    The mount program must understand the PARTUUID syntax you use with
-   ``--use-uuid`` and non-root *mountpoint*, including swap. The busybox
+   ``--use-uuid`` and non-root *mountpoint*, including swap. The BusyBox
    versions of these application are currently excluded.
 
 Here is an example that uses "/" as the mountpoint. The command uses
diff --git a/poky/documentation/ref-manual/migration-1.3.rst b/poky/documentation/ref-manual/migration-1.3.rst
index 12e225b..0929f49 100644
--- a/poky/documentation/ref-manual/migration-1.3.rst
+++ b/poky/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/poky/documentation/ref-manual/migration-1.4.rst b/poky/documentation/ref-manual/migration-1.4.rst
index 0b7e861..f5fac7a 100644
--- a/poky/documentation/ref-manual/migration-1.4.rst
+++ b/poky/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/poky/documentation/ref-manual/migration-1.5.rst b/poky/documentation/ref-manual/migration-1.5.rst
index 2716bc9..c772e51 100644
--- a/poky/documentation/ref-manual/migration-1.5.rst
+++ b/poky/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:
 
@@ -298,7 +298,7 @@
 -  ``libtool-nativesdk`` has been renamed to ``nativesdk-libtool``.
 
 -  ``tinylogin`` has been removed. It has been replaced by a suid
-   portion of Busybox. See the "`BusyBox <#busybox>`__"
+   portion of Busybox. See the ":ref:`migration-1.5-busybox`"
    section for more information.
 
 -  ``external-python-tarball`` has been renamed to
diff --git a/poky/documentation/ref-manual/migration-1.6.rst b/poky/documentation/ref-manual/migration-1.6.rst
index ed155d0..4c6afab 100644
--- a/poky/documentation/ref-manual/migration-1.6.rst
+++ b/poky/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/poky/documentation/ref-manual/migration-1.7.rst b/poky/documentation/ref-manual/migration-1.7.rst
index 54544e4..9cf467f 100644
--- a/poky/documentation/ref-manual/migration-1.7.rst
+++ b/poky/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:
 
@@ -12,7 +12,7 @@
 The QEMU recipe now uses a number of
 :term:`PACKAGECONFIG` options to enable various
 optional features. The method used to set defaults for these options
-means that existing ``local.conf`` files will need to be be modified to
+means that existing ``local.conf`` files will need to be modified to
 append to ``PACKAGECONFIG`` for ``qemu-native`` and ``nativesdk-qemu``
 instead of setting it. In other words, to enable graphical output for
 QEMU, you should now have these lines in ``local.conf``:
diff --git a/poky/documentation/ref-manual/migration-1.8.rst b/poky/documentation/ref-manual/migration-1.8.rst
index 73789bd..ec2b138 100644
--- a/poky/documentation/ref-manual/migration-1.8.rst
+++ b/poky/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/poky/documentation/ref-manual/migration-2.0.rst b/poky/documentation/ref-manual/migration-2.0.rst
index 4eea948..9da60df 100644
--- a/poky/documentation/ref-manual/migration-2.0.rst
+++ b/poky/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/poky/documentation/ref-manual/migration-2.1.rst b/poky/documentation/ref-manual/migration-2.1.rst
index 861d048..1eb9ab5 100644
--- a/poky/documentation/ref-manual/migration-2.1.rst
+++ b/poky/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:
 
@@ -134,7 +134,7 @@
 In particular, if you had added any tasks after ``do_rootfs``, you
 should make edits so that those tasks are after the
 :ref:`ref-tasks-image-complete` task rather than
-after ``do_rootfs`` so that the your added tasks run at the correct
+after ``do_rootfs`` so that your added tasks run at the correct
 time.
 
 A minor part of this restructuring is that the post-processing
@@ -179,9 +179,8 @@
 
 -  ``python-pygtk``: Recipe became obsolete.
 
--  ``adt-installer``: Recipe became obsolete. See the "`ADT
-   Removed <#adt-removed>`__" section for more
-   information.
+-  ``adt-installer``: Recipe became obsolete. See the
+   ":ref:`ref-manual/migration-2.1:adt removed`" section for more information.
 
 .. _migration-2.1-class-changes:
 
diff --git a/poky/documentation/ref-manual/migration-2.2.rst b/poky/documentation/ref-manual/migration-2.2.rst
index 5c6fecf..198181a 100644
--- a/poky/documentation/ref-manual/migration-2.2.rst
+++ b/poky/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:
 
@@ -367,8 +367,8 @@
 
 -  ``sato-icon-theme``: Became obsolete.
 
--  ``swabber-native``: Swabber has been removed. See the `entry on
-   Swabber <#swabber-has-been-removed>`__.
+-  ``swabber-native``: Swabber has been removed. See the :ref:`entry on
+   Swabber <ref-manual/migration-2.2:swabber has been removed>`.
 
 -  ``tslib``: No longer needed and has been moved to ``meta-oe``.
 
@@ -393,8 +393,8 @@
 
 -  ``sip``: Mostly unused.
 
--  ``swabber``: See the `entry on
-   Swabber <#swabber-has-been-removed>`__.
+-  ``swabber``: See the :ref:`entry on
+   Swabber <ref-manual/migration-2.2:swabber has been removed>`.
 
 .. _migration-2.2-minor-packaging-changes:
 
diff --git a/poky/documentation/ref-manual/migration-2.3.rst b/poky/documentation/ref-manual/migration-2.3.rst
index 04b11da..0541eb3 100644
--- a/poky/documentation/ref-manual/migration-2.3.rst
+++ b/poky/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/poky/documentation/ref-manual/migration-2.4.rst b/poky/documentation/ref-manual/migration-2.4.rst
index 260b320..2ba17e0 100644
--- a/poky/documentation/ref-manual/migration-2.4.rst
+++ b/poky/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/poky/documentation/ref-manual/migration-2.5.rst b/poky/documentation/ref-manual/migration-2.5.rst
index 9f45ffc..9ef4b55 100644
--- a/poky/documentation/ref-manual/migration-2.5.rst
+++ b/poky/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/poky/documentation/ref-manual/migration-2.6.rst b/poky/documentation/ref-manual/migration-2.6.rst
index 5d524f3..aeac509 100644
--- a/poky/documentation/ref-manual/migration-2.6.rst
+++ b/poky/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:
 
@@ -110,7 +110,7 @@
 newer ``xorgproto`` recipe instead.
 
 For names of recipes removed because of this repository change, see the
-`Removed Recipes <#removed-recipes>`__ section.
+:ref:`ref-manual/migration-2.6:removed recipes` section.
 
 .. _migration-2.6-distutils-distutils3-fetching-dependencies:
 
@@ -118,7 +118,7 @@
 ---------------------------------------------------------------------------------------------------
 
 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/poky/documentation/ref-manual/migration-2.7.rst b/poky/documentation/ref-manual/migration-2.7.rst
index 5af5947..1be4d5d 100644
--- a/poky/documentation/ref-manual/migration-2.7.rst
+++ b/poky/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/poky/documentation/ref-manual/migration-3.0.rst b/poky/documentation/ref-manual/migration-3.0.rst
index 7ef2742..f3d20e2 100644
--- a/poky/documentation/ref-manual/migration-3.0.rst
+++ b/poky/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/poky/documentation/ref-manual/migration-3.1.rst b/poky/documentation/ref-manual/migration-3.1.rst
index 4fcd249..84d3250 100644
--- a/poky/documentation/ref-manual/migration-3.1.rst
+++ b/poky/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/poky/documentation/ref-manual/migration-3.2.rst b/poky/documentation/ref-manual/migration-3.2.rst
index 65a9ff4..39743af 100644
--- a/poky/documentation/ref-manual/migration-3.2.rst
+++ b/poky/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:
 
@@ -308,6 +308,6 @@
 - Erroneous use of ``inherit +=`` (instead of ``INHERIT +=``) in a configuration file now triggers an error instead of silently being ignored.
 - ptest support has been removed from the ``kbd`` recipe, as upstream has moved to autotest which is difficult to work with in a cross-compilation environment.
 - ``oe.utils.is_machine_specific()`` and ``oe.utils.machine_paths()`` have been removed as their utility was questionable. In the unlikely event that you have references to these in your own code, then the code will need to be reworked.
-- The ``i2ctransfer`` module is now disabled by default when building ``busybox`` in order to be consistent with disabling the other i2c tools there. If you do wish the i2ctransfer module to be built in busybox then add ``CONFIG_I2CTRANSFER=y`` to your custom busybox configuration.
+- The ``i2ctransfer`` module is now disabled by default when building ``busybox`` in order to be consistent with disabling the other i2c tools there. If you do wish the i2ctransfer module to be built in BusyBox then add ``CONFIG_I2CTRANSFER=y`` to your custom BusyBox configuration.
 - In the ``Upstream-Status`` header convention for patches, ``Accepted`` has been replaced with ``Backport`` as these almost always mean the same thing i.e. the patch is already upstream and may need to be removed in a future recipe upgrade. If you are adding these headers to your own patches then use ``Backport`` to indicate that the patch has been sent upstream.
 - The ``tune-supersparc.inc`` tune file has been removed as it does not appear to be widely used and no longer works.
diff --git a/poky/documentation/ref-manual/migration-3.3.rst b/poky/documentation/ref-manual/migration-3.3.rst
new file mode 100644
index 0000000..4fb51a3
--- /dev/null
+++ b/poky/documentation/ref-manual/migration-3.3.rst
@@ -0,0 +1,168 @@
+Moving to the Yocto Project 3.3 Release (hardknott)
+===================================================
+
+This section provides migration information for moving to the Yocto
+Project 3.3 Release (codename "hardknott") 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-distutils-path:
+
+``setup.py`` path for python modules
+------------------------------------
+
+In a Python module, sometimes ``setup.py`` can be buried deep in the
+source tree. Previously this was handled in recipes by setting :term:`S` to
+point to the subdirectory within the source where ``setup.py`` is located.
+However with the recent :ref:`pseudo <overview-manual/concepts:fakeroot and pseudo>`
+changes, some Python modules make changes to files beneath ``${S}``, for
+example::
+
+   S = "${WORKDIR}/git/python/pythonmodule"
+
+then in ``setup.py`` it works with source code in a relative fashion, such
+as ``../../src``. This causes pseudo to abort as it isn't able to track
+the paths properly. This release introduces a new :term:`DISTUTILS_SETUP_PATH`
+variable so that recipes can specify it explicitly, for example::
+
+   S = "${WORKDIR}/git"
+   DISTUTILS_SETUP_PATH = "${S}/python/pythonmodule"
+
+Recipes that inherit from :ref:`distutils3 <ref-classes-distutils3>` (or
+:ref:`setuptools3 <ref-classes-setuptools3>` which itself inherits
+:ref:`distutils3 <ref-classes-distutils3>`) that also set :term:`S` to
+point to a Python module within a subdirectory in the aforementioned
+manner should be changed to set :term:`DISTUTILS_SETUP_PATH` instead.
+
+
+.. _migration-3.3-bitbake:
+
+BitBake changes
+---------------
+
+- BitBake is now configured to use a default ``umask`` of ``022`` for all tasks
+  (specified via a new :term:`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 :term:`DISTRO_VERSION` value as desired
+  (particularly if you create your own custom distro configuration).
+- ``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/poky/documentation/ref-manual/migration.rst b/poky/documentation/ref-manual/migration.rst
index 8d64a7d..a01d4ee 100644
--- a/poky/documentation/ref-manual/migration.rst
+++ b/poky/documentation/ref-manual/migration.rst
@@ -28,4 +28,5 @@
    migration-3.0
    migration-3.1
    migration-3.2
+   migration-3.3
 
diff --git a/poky/documentation/ref-manual/release-process.rst b/poky/documentation/ref-manual/release-process.rst
index ed5a09a..93ab6ed 100644
--- a/poky/documentation/ref-manual/release-process.rst
+++ b/poky/documentation/ref-manual/release-process.rst
@@ -15,9 +15,8 @@
 The Yocto Project delivers major releases (e.g. &DISTRO;) using a six
 month cadence roughly timed each April and October of the year.
 Following are examples of some major YP releases with their codenames
-also shown. See the "`Major Release
-Codenames <#major-release-codenames>`__" section for information on
-codenames used with major releases.
+also shown. See the ":ref:`ref-manual/release-process:major release codenames`"
+section for information on codenames used with major releases.
 
   - 2.2 (Morty) 
   - 2.1 (Krogoth)
@@ -135,7 +134,7 @@
 
 -  :ref:`ptest <dev-manual/common-tasks:testing packages with ptest>`:
    Runs tests against packages produced during the build for a given
-   piece of software. The test allows the packages to be be run within a
+   piece of software. The test allows the packages to be run within a
    target image.
 
 -  ``oe-selftest``: Tests combination BitBake invocations. These tests
diff --git a/poky/documentation/ref-manual/resources.rst b/poky/documentation/ref-manual/resources.rst
index 7554164..663f0d9 100644
--- a/poky/documentation/ref-manual/resources.rst
+++ b/poky/documentation/ref-manual/resources.rst
@@ -91,7 +91,7 @@
 Internet Relay Chat (IRC)
 =========================
 
-Two IRC channels on freenode are available for the Yocto Project and
+Two IRC channels on Freenode are available for the Yocto Project and
 Poky discussions:
 
 -  ``#yocto``
@@ -189,7 +189,7 @@
    implementation of Bugzilla for logging and tracking Yocto Project
    defects.
 
--  *Internet Relay Chat (IRC):* Two IRC channels on freenode are
+-  *Internet Relay Chat (IRC):* Two IRC channels on Freenode are
    available for Yocto Project and Poky discussions: ``#yocto`` and
    ``#poky``, respectively.
 
diff --git a/poky/documentation/ref-manual/structure.rst b/poky/documentation/ref-manual/structure.rst
index ad3f4ab..0f2093a 100644
--- a/poky/documentation/ref-manual/structure.rst
+++ b/poky/documentation/ref-manual/structure.rst
@@ -168,7 +168,7 @@
        meta-toolchain
        meta-ide-support
 
-   You can also run generated qemu images with a command like 'runqemu qemux86-64'
+   You can also run generated QEMU images with a command like 'runqemu qemux86-64'
 
 The default output of the ``oe-init-build-env`` script is from the
 ``conf-notes.txt`` file, which is found in the ``meta-poky`` directory
diff --git a/poky/documentation/ref-manual/system-requirements.rst b/poky/documentation/ref-manual/system-requirements.rst
index c8c1381..80378ce 100644
--- a/poky/documentation/ref-manual/system-requirements.rst
+++ b/poky/documentation/ref-manual/system-requirements.rst
@@ -59,7 +59,7 @@
 
 -  Debian GNU/Linux 10.x (Buster)
 
--  OpenSUSE Leap 15.1
+-  openSUSE Leap 15.1
 
 
 .. note::
@@ -256,11 +256,11 @@
 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,11 +270,15 @@
 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
-contains additional tools, the equivalent of ``buildtools-essential``.
+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
 --------------------------------------------------------------------------------
@@ -294,7 +298,7 @@
 
    During execution, the buildtools tarball will be downloaded, the
    checksum of the download will be verified, the installer will be run
-   for you, and some basic checks will be run to to make sure the
+   for you, and some basic checks will be run to make sure the
    installation is functional.
 
    To avoid the need of ``sudo`` privileges, the ``install-buildtools``
@@ -331,8 +335,9 @@
 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/
 
diff --git a/poky/documentation/ref-manual/variables.rst b/poky/documentation/ref-manual/variables.rst
index 0310429..74ac12b 100644
--- a/poky/documentation/ref-manual/variables.rst
+++ b/poky/documentation/ref-manual/variables.rst
@@ -768,9 +768,7 @@
       .. note::
 
          If you run BitBake from a directory outside of the
-         Build Directory
-         , you must be sure to set
-         BBPATH
+         :term:`Build Directory`, you must be sure to set ``BBPATH``
          to point to the Build Directory. Set the variable as you would any
          environment variable and then run BitBake:
          ::
@@ -1980,6 +1978,19 @@
       is included in the default value of
       :term:`OVERRIDES`.
 
+   :term:`DISTUTILS_SETUP_PATH`
+      When used by recipes that inherit the
+      :ref:`distutils3 <ref-classes-distutils3>` or
+      :ref:`setuptools3 <ref-classes-setuptools3>` class, this variable should
+      be used to specify the directory in which the ``setup.py`` file is
+      located if it is not at the root of the source tree (as specified by
+      :term:`S`). For example, in a recipe where the sources are fetched from
+      a Git repository and ``setup.py`` is in a ``python/pythonmodule``
+      subdirectory, you would have this::
+
+         S = "${WORKDIR}/git"
+         DISTUTILS_SETUP_PATH = "${S}/python/pythonmodule"
+
    :term:`DL_DIR`
       The central download directory used by the build process to store
       downloads. By default, ``DL_DIR`` gets files suitable for mirroring
@@ -2295,6 +2306,17 @@
          # 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`.
@@ -2571,6 +2593,16 @@
    :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 FIT Image.
+      At present, the only supported values are "gzip" (default) or "none"
+      If you set this variable to anything other than "none" you may 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".
+
    :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
@@ -2582,7 +2614,7 @@
       and new for generating new keys.
 
    :term:`FIT_KEY_SIGN_PKCS`
-      Format for public key ceritifcate used in signing fitImage.
+      Format for public key certificate used in signing fitImage.
       The default value is "x509".
 
    :term:`FIT_SIGN_ALG`
@@ -2991,7 +3023,7 @@
 
    :term:`IMAGE_CMD`
       Specifies the command to create the image file for a specific image
-      type, which corresponds to the value set set in
+      type, which corresponds to the value set in
       :term:`IMAGE_FSTYPES`, (e.g. ``ext3``,
       ``btrfs``, and so forth). When setting this variable, you should use
       an override for the associated type. Here is an example:
@@ -3449,7 +3481,7 @@
 
          It is possible to define a list of licenses that are allowed to be
          used instead of the licenses that are excluded. To do this, define
-         a variable ``COMPATIBLE_LICENSES`` with the names of the licences
+         a variable ``COMPATIBLE_LICENSES`` with the names of the licenses
          that are allowed. Then define ``INCOMPATIBLE_LICENSE`` as:
          ::
 
@@ -3457,8 +3489,8 @@
 
 
          This will result in ``INCOMPATIBLE_LICENSE`` containing the names of
-         all licences from :term:`AVAILABLE_LICENSES` except the ones specified
-         in ``COMPATIBLE_LICENSES`` , thus only allowing the latter licences to
+         all licenses from :term:`AVAILABLE_LICENSES` except the ones specified
+         in ``COMPATIBLE_LICENSES``, thus only allowing the latter licenses to
          be used.
 
    :term:`INHERIT`
@@ -4661,6 +4693,14 @@
    :term:`MAINTAINER`
       The email address of the distribution maintainer.
 
+   :term:`METADATA_BRANCH`
+      The branch currently checked out for the OpenEmbedded-Core layer (path
+      determined by :term:`COREBASE`).
+
+   :term:`METADATA_REVISION`
+      The revision currently checked out for the OpenEmbedded-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
@@ -5011,7 +5051,7 @@
          ${PN}-${PV}
 
    :term:`PACKAGE_ADD_METADATA`
-      This variable defines additional metdata to add to packages.
+      This variable defines additional metadata to add to packages.
 
       You may find you need to inject additional metadata into packages.
       This variable allows you to do that by setting the injected data as
@@ -5792,10 +5832,11 @@
          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 (`python` in
+      the first example below), and you should specify 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
@@ -5853,6 +5894,10 @@
          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
@@ -6019,9 +6064,7 @@
    :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.
@@ -6030,16 +6073,14 @@
       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.
@@ -6210,6 +6251,17 @@
       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.
+      :term:`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 :term:`REQUIRED_VERSION` and :term:`PREFERRED_VERSION` are set
+      for the same recipe, the :term:`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
@@ -6483,6 +6535,11 @@
       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
+      (:term:`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
@@ -6758,16 +6815,16 @@
       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
@@ -7092,7 +7149,7 @@
       -  ``git://`` - Fetches files from a Git revision control
          repository.
 
-      -  ``osc://`` - Fetches files from an OSC (OpenSUSE Build service)
+      -  ``osc://`` - Fetches files from an OSC (openSUSE Build service)
          revision control repository.
 
       -  ``repo://`` - Fetches files from a repo (Git) repository.