Add property documentation_reference for usage in READMEs

The current `reference` property is usually too detailed for user facing
documentation, where a shorter version is sufficient.

Author: dcermak

src/bci_build/package/__init__.py

@@ -957,6 +957,16 @@ def reference(self) -> str:
         """
         pass
 
+    @property
+    @abc.abstractmethod
+    def documentation_reference(self) -> str:
+        """The reference via which this image can be pulled, but not necessarily
+        a fully unique version. This url shall point to a reasonable compromise
+        to be used in the documentation, e.g. only the major version and not
+        including the release.
+
+        """
+
     @property
     def description(self) -> str:
         """The description of this image which is inserted into the
@@ -1324,6 +1334,12 @@ def reference(self) -> str:
             + f":{self.version_label}-{self._release_suffix}"
         )
 
+    @property
+    def documentation_reference(self) -> str:
+        return f"{self.registry}/{self._registry_prefix}/{self.name}:" + (
+            "latest" if self.is_latest else self.version_label
+        )
+
     @property
     def build_version(self) -> Optional[str]:
         build_ver = super().build_version
@@ -1398,6 +1414,10 @@ def build_tags(self) -> List[str]:
     def reference(self) -> str:
         return f"{self.registry}/{self._registry_prefix}/bci-{self.name}:{self.version_label}"
 
+    @property
+    def documentation_reference(self) -> str:
+        return f"{self.registry}/{self._registry_prefix}/bci-{self.name}:%OS_VERSION_ID_SP%"
+
 
 def generate_disk_size_constraints(size_gb: int) -> str:
     """Creates the contents of a :file:`_constraints` file for OBS to require