migration-general: add section on using buildhistory

Add a short section recommending the use of buildhistory to compare
the build output before and after migration.

(From yocto-docs rev: e4a83dadbda563e08302055538203c9b1ac9e992)

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 33 insertions, 0 deletions

diff --git a/documentation/migration-guides/migration-general.rst b/documentation/migration-guides/migration-general.rst
index 9eecf69af8..0f0408e51f 100644
--- a/documentation/migration-guides/migration-general.rst
+++ b/documentation/migration-guides/migration-general.rst
@@ -70,3 +70,36 @@ any new Yocto Project release.
      bitbake-layers show-appends
 
 
+.. _migration-general-buildhistory:
+
+- *Checking Image / SDK Changes*:
+
+   The :ref:`buildhistory <ref-classes-buildhistory>` class can be used
+   if you wish to check the impact of changes to images / SDKs across
+   the migration (e.g. added/removed packages, added/removed files, size
+   changes etc.). To do this, follow these steps:
+
+   1. Enable buildhistory before the migration
+
+   2. Run a pre-migration build
+
+   3. Capture the buildhistory output (as specified by :term:`BUILDHISTORY_DIR`)
+      and ensure it is preserved for subsequent builds. How you would do this
+      depends on how you are running your builds - if you are doing this all on
+      one workstation in the same build directory you may not need to do
+      anything other than not deleting the buildhistory output directory. For
+      builds in a pipeline it may be more complicated.
+
+   4. Set a tag in the buildhistory output (which is a git repository) before
+      migration, to make the commit from the pre-migration build easy to find
+      as you may end up running multiple builds during the migration.
+
+   5. Perform the migration
+
+   6. Run a build
+
+   7. Check the output changes between the previously set tag and HEAD in the
+      buildhistory output using ``git diff`` or ``buildhistory-diff``.
+
+   For more information on using buildhistory, see
+   :ref:`dev-manual/common-tasks:maintaining build output quality`.