[PATCH 01/34] migration-general: add section on using buildhistory

Paul Eggleton
2022-10-10T09:24:43Z

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

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
.../migration-guides/migration-general.rst | 33 ++++++++++++++++++++++
1 file changed, 33 insertions(+)

diff --git a/documentation/migration-guides/migration-general.rst b/documentation/migration-guides/migration-general.rst
index 9eecf69..8b22508 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 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`.
--
1.8.3.1