docs: Add release note about building for other distros

docs/news/unreleased/other-distro-build.md

@@ -0,0 +1,145 @@
+# Building images for other distributions
+
+Previously osbuild-composer could only build images for the same distribution
+as the host. With the addition of the distro field in blueprint it is now
+possible to build for any supported distribution shipped with osbuild-composer.
+
+
+## New API route: /distros/list
+
+The API now supports listing the available distributions. It will return a JSON
+object listing the installed distro names that can be used by blueprints,
+sources, and the optional `?distro=` selection on API routes.
+
+eg. `curl --unix-socket /run/weldr/api.socket http://localhost/api/v1/distros/list`
+
+    {
+        "distros": [
+            "centos-8",
+            "fedora-32",
+            "fedora-33",
+            "rhel-8",
+            "rhel-84",
+            "rhel-85",
+            "rhel-90"
+        ]
+    }
+
+
+## Distribution selection with blueprints
+
+The blueprint now supports a new `distro` field that will be used to select the
+distribution to use when composing images, or depsolving the blueprint. If
+`distro` is left blank it will use the host distribution. If you upgrade the
+host operating system the blueprints with no `distro` set will build using the
+new os.
+
+eg. A blueprint that will always build a fedora-32 image, no matter what
+version is running on the host:
+
+    name = "tmux"
+    description = "tmux image with openssh"
+    version = "1.2.16"
+    distro = "fedora-32"
+
+    [[packages]]
+    name = "tmux"
+    version = "*"
+
+    [[packages]]
+    name = "openssh-server"
+    version = "*"
+
+
+## Using sources with specific distributions
+
+A new optional field has been added to the repository source format. It is a
+list of distribution strings that the source will be used with when depsolving
+and building images.
+
+Sources with no `distros` will be used with all composes. If you want to use a
+source for a specific distro you set the `distros` list to the distro name(s)
+to use it with.
+
+eg. A source that is only used when depsolving or building fedora 32:
+
+    check_gpg = true
+    check_ssl = true
+    distros = ["fedora-32"]
+    id = "f32-local"
+    name = "local packages for fedora32"
+    system = false
+    type = "yum-baseurl"
+    url = "http://local/repos/fedora32/projectrepo/"
+
+This source will be used for any requests that specify fedora-32, eg. listing
+packages and specifying fedora-32 will include this source, but listing
+packages for the host distro will not.
+
+
+## Optional distribution selection for routes
+
+Many of the API routes now support selecting the distribution to use when
+returning results.  Add `?distro=<DISTRO-NAME>` to the API request and it will
+return results using `fedora-32` instead of the host distro.
+
+The following routes support distro selection:
+
+* /compose/types
+* /modules/list
+* /modules/info
+* /projects/list
+* /projects/info
+* /projects/depsolve
+
+The compose start uses the distribution specified by the blueprint to select
+which one to use.
+
+eg. Show the image types supported by `centos-8`:
+
+    curl --unix-socket /run/weldr/api.socket http://localhost/api/v1/compose/types?distro=centos-8
+    {
+        "types": [
+            {
+                "name": "ami",
+                "enabled": true
+            },
+            {
+                "name": "openstack",
+                "enabled": true
+            },
+            {
+                "name": "qcow2",
+                "enabled": true
+            },
+            {
+                "name": "tar",
+                "enabled": true
+            },
+            {
+                "name": "vhd",
+                "enabled": true
+            },
+            {
+                "name": "vmdk",
+                "enabled": true
+            }
+        ]
+    }
+
+
+## Unknown Distributions
+
+If an unknown distribution is selected the response from the API server will be
+a `DistroError`, like this:
+
+    {
+        "status": false,
+        "errors": [
+            {
+                "id": "DistroError",
+                "msg": "Invalid distro: fedora-1"
+            }
+        ]
+    }
+