docs/package-notes: extend motivation and recommendations

We described the "how", but not the "why". And the text was a bit dated,
still mostly talking about core files. Let's make it more general
and describe why a section is used.

Add a recommendation/explanation for the debugInfoUrl field.

diff --git a/docs/PACKAGE_METADATA_FOR_EXECUTABLE_FILES.md b/docs/PACKAGE_METADATA_FOR_EXECUTABLE_FILES.md
index 73454ceed1765cc5ed4bbbb06c4285c506f119cb..1aa8734bced99d4c27e0fbb342091ecd9d7d8b38 100644 (file)
--- a/docs/PACKAGE_METADATA_FOR_EXECUTABLE_FILES.md
+++ b/docs/PACKAGE_METADATA_FOR_EXECUTABLE_FILES.md
@@ -27,6 +27,14 @@ Thus it becomes desirable to add additional metadata to a binary at build time,
 `systemd-coredump` and other services analyzing core files are able to extract said
 metadata simply from the core file itself, without external dependencies.
 
+This metadata is stored as a section in the executable file,
+so that it will be loaded into memory along with the text and data of the binary,
+and will be preserved in a core dump.
+This metadata can also be easily read from the file on disk,
+so it can be used to identify provenience of files,
+independently of any package management system,
+even if the file is renamed or copied.
+
 ## Implementation
 
 This document will attempt to define a common metadata format specification, so that
@@ -81,6 +89,9 @@ these JSON objects are thus permitted to encode numeric values from these
 ranges as JSON numbers, and should not use numeric values not covered by these
 types and ranges.
 
+If available, the metadata should also include the debuginfod server URL that can provide
+the original executable, debuginfo and sources, to further facilitate debugging.
+
 Reference implementations of [packaging tools for .deb and .rpm](https://github.com/systemd/package-notes)
 are available, and provide macros/helpers to include the note in binaries built
 by the package build system.