diff --git a/docs/index.rst b/docs/index.rst
index 84bd1126..787ce717 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -47,3 +47,4 @@ If you're looking for a CycloneDX tool to run to generate (SBOM) software bill-o
    contributing
    support
    changelog
+   upgrading
diff --git a/docs/upgrading.rst b/docs/upgrading.rst
new file mode 100644
index 00000000..6f9e8cff
--- /dev/null
+++ b/docs/upgrading.rst
@@ -0,0 +1,62 @@
+Upgrading to v8
+===============
+
+Version 8 is not backwards compatible. Some behaviours and integrations changed.
+This document covers all breaking changes and should give guidance how to migrate from previous versions.
+
+This document is not a full :doc:`change log <changelog>`, but a migration path.
+
+Add this library to Metadata Tools
+----------------------------------
+
+This library no longer adds itself to the metadata.
+
+Downstream users SHOULD add the following to their BOM build processes,
+to keep track of used libraries during the build process.
+
+.. code-block:: python
+
+    from cyclonedx.builder.this import this_component as cdx_lib_component
+    from cyclonedx.model.bom import Bom
+
+    bom = Bom()
+    bom.metadata.tools.components.add(cdx_lib_component())
+
+Import model Tool
+-----------------
+
+Class `cyclonedx.model.Tool` was moved to :class:`cyclonedx.model.tool.Tool`.
+Therefore, the imports need to be migrated:
+
+Old: ``from cyclonedx.model import Tool``
+
+New: ``from cyclonedx.model.tool import Tool``
+
+Alter Metadata Tools
+--------------------
+
+Property :attr:`cyclonedx.model.bom.BomMetaData.tools` is an instance of :class:`cyclonedx.model.tool.ToolsRepository`, now.
+Therefore, the process of adding new tools needs to be migrated changed.
+
+Old: ``my_bom.metadata.tools.add(my_tool)``
+
+New: ``my_bom.metadata.tools.tools.add(my_tool)``
+
+Alter Vulnerability Tools
+-------------------------
+
+Property :attr:`cyclonedx.model.vulnerability.Vulnerability.tools` is an instance of :class:`cyclonedx.model.tool.ToolsRepository`, now.
+Therefore, the process of adding new tools needs to be migrated changed.
+
+Old: ``my_vulnerability.tools.add(my_tool)``
+
+New: ``my_vulnerability.tools.tools.add(my_tool)``
+
+Set LicenseExpression Acknowledgement
+-------------------------------------
+
+:class:`cyclonedx.model.license.LicenseExpression()` no longer accepts optional arguments in a positional way, but in a key-word way.
+
+Old: ``LicenseExpression(my_exp, my_acknowledgement)``
+
+New: ``LicenseExpression(my_exp, acknowledgement=my_acknowledgement)``
diff --git a/examples/complex_serialize.py b/examples/complex_serialize.py
index 477e7ee5..6448a2a7 100644
--- a/examples/complex_serialize.py
+++ b/examples/complex_serialize.py
@@ -20,6 +20,7 @@
 
 from packageurl import PackageURL
 
+from cyclonedx.builder.this import this_component as cdx_lib_component
 from cyclonedx.exception import MissingOptionalDependencyException
 from cyclonedx.factory.license import LicenseFactory
 from cyclonedx.model import XsUri
@@ -43,6 +44,8 @@
 # region build the BOM
 
 bom = Bom()
+bom.metadata.tools.components.add(cdx_lib_component())
+
 bom.metadata.component = root_component = Component(
     name='myApp',
     type=ComponentType.APPLICATION,