[PATCH 2/3] doc: Restore API-CHANGELOG entry for artifacts naming and path changes

[Zhihang Wei <wzh@ilbers.de>]

To keep it clear for users what API changes (13cb77dd) were introduced
in Isar v1.0 and subsequently reverted (79e10791), the API-CHANGELOG
is restored and updated.

Signed-off-by: Zhihang Wei <wzh@ilbers.de>
---
 RECIPE-API-CHANGELOG.md | 86 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)

diff --git a/RECIPE-API-CHANGELOG.md b/RECIPE-API-CHANGELOG.md
index 0e6a3172..659a03b0 100644
--- a/RECIPE-API-CHANGELOG.md
+++ b/RECIPE-API-CHANGELOG.md
@@ -981,3 +981,89 @@ fragment, this can be specified via adding `${S}/path/to/fragment.cfg` to
 `KERNEL_CONFIG_FRAGMENTS`. If a fragment was checked out into ${WORKDIR} as
 part of a repository, a tarball, or some other directory structure, just
 specify it relative to ${WORKDIR} in `KERNEL_CONFIG_FRAGMENTS`.
+
+### Change DEPLOY_DIR_IMAGE path and artifacts naming
+
+Change DEPLOY_DIR_IMAGE from ${DEPLOY_DIR}/images/${MACHINE} to
+${DEPLOY_DIR}/images/${MACHINE}/${DISTRO}-${IMAGE_PN}.
+
+When building different distros with the same machine the following
+error occurs:
+
+do_copy_boot_files: The recipe isar-image-base is trying to install
+files into a shared area when those files already exists. It happens
+when some files have the same names (e.g., dtb files) for different
+distros.
+
+To prevent such collisions, image artifacts are now deployed into a
+distro- and image-specific subdirectory.
+
+Additionally, artifact filenames have been shortened by removing the
+${DISTRO} and ${IMAGE_PN} prefix, since this information is now
+encoded in the directory path.
+
+Example 1: Build isar-image-base (phyboard-mira, debian-bookworm)
+Under "build/tmp/deploy/images/":
+Before:
+phyboard-mira/imx6q-phytec-mira-rdk-nand.dtb
+phyboard-mira/isar-image-base-debian-bookworm-phyboard-mira-initrd.img
+phyboard-mira/isar-image-base-debian-bookworm-phyboard-mira-vmlinuz
+phyboard-mira/isar-image-base-debian-bookworm-phyboard-mira.dpkg_status
+phyboard-mira/isar-image-base-debian-bookworm-phyboard-mira.ubi
+
+After:
+phyboard-mira/debian-bookworm-isar-image-base/imx6q-phytec-mira-rdk-nand.dtb
+phyboard-mira/debian-bookworm-isar-image-base/initrd.img
+phyboard-mira/debian-bookworm-isar-image-base/vmlinuz
+phyboard-mira/debian-bookworm-isar-image-base/phyboard-mira.dpkg_status
+phyboard-mira/debian-bookworm-isar-image-base/phyboard-mira.ubi
+
+Example 2: Build isar-image-ci (qemuamd64, debian-bookworm)
+Under "build/tmp/deploy/images/":
+Before:
+qemuamd64/isar-image-ci-debian-bookworm-qemuamd64-initrd.img
+qemuamd64/isar-image-ci-debian-bookworm-qemuamd64-vmlinuz
+qemuamd64/isar-image-ci-debian-bookworm-qemuamd64.dpkg_status
+qemuamd64/isar-image-ci-debian-bookworm-qemuamd64.manifest
+qemuamd64/isar-image-ci-debian-bookworm-qemuamd64.wic
+qemuamd64/isar-image-ci-debian-bookworm-qemuamd64.wic.bmap
+qemuamd64/isar-image-ci-debian-bookworm-qemuamd64.wic.manifest
+
+After:
+qemuamd64/debian-bookworm-isar-image-ci/initrd.img
+qemuamd64/debian-bookworm-isar-image-ci/vmlinuz
+qemuamd64/debian-bookworm-isar-image-ci/qemuamd64.dpkg_status
+qemuamd64/debian-bookworm-isar-image-ci/qemuamd64.manifest
+qemuamd64/debian-bookworm-isar-image-ci/qemuamd64.wic
+qemuamd64/debian-bookworm-isar-image-ci/qemuamd64.wic.bmap
+qemuamd64/debian-bookworm-isar-image-ci/qemuamd64.wic.manifest
+
+Artifacts that do not belong to a full image (e.g. isar-image-base,
+isar-image-ci) remain unchanged. For example, a customized initramfs
+built independently is not affected.
+
+This change affects the location and naming of build artifacts and must
+be taken into account by downstream users.
+
+Note that this approach differs from OpenEmbedded.
+
+OpenEmbedded typically avoids artifact collisions in multiconfig builds
+by using separate TMPDIRs per configuration, resulting in multiple
+build directories such as tmp-qemuarm64 and tmp-qemuarm64customized. In
+this model, artifacts with identical names but different contents do
+not cause conflicts because they reside in their own isolated build
+directories.
+
+If multiple configurations are intentionally configured to share the
+same TMPDIR in OpenEmbedded, conflicts may occur and are not handled by
+OE. Artifacts with the same name overwrite each other, leading to
+incorrect build results.
+
+Changes in next
+---------------
+
+### Revert "Change DEPLOY_DIR_IMAGE path and artifacts naming"
+
+The DEPLOY_DIR_IMAGE path and artifacts naming changes introduced in
+13cb77dd (included in Isar v1.0) have been reverted. Deployment paths
+and artifact names are the same as pre-v1.0.
-- 
2.39.5

-- 
You received this message because you are subscribed to the Google Groups "isar-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to isar-users+unsubscribe@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/isar-users/20260423121941.1704827-2-wzh%40ilbers.de.