Merge branch 'issues/13'

* issues/13:
  Add documentation on release artifacts
  Move build artifacts to per-type release directories

.gitlab/ci/build_releng.sh

@@ -22,6 +22,7 @@ readonly app_name="${0##*/}"
 
 tmpdir=""
 tmpdir="$(mktemp --dry-run --directory --tmpdir="${tmpdir_base}")"
+version="$(date +%Y.%m.%d)"
 gnupg_homedir=""
 codesigning_dir=""
 codesigning_cert=""
@@ -242,7 +243,7 @@ check_codesigning_cert_validity() {
 copy_ipxe_binaries() {
   # copy ipxe binaries to output dir
   local _ipxe_base="/usr/share/ipxe"
-  local _ipxe_output="${output}/ipxe"
+  local _ipxe_output="${output}/ipxe/ipxe-${version}"
 
   print_section_start "copy_ipxe" "Copy iPXE binaries"
 
@@ -250,6 +251,32 @@ copy_ipxe_binaries() {
   cp -av -- "${_ipxe_base}/"{ipxe-arch.{lkrn,pxe},x86_64/ipxe-arch.efi} "${_ipxe_output}"
 
   print_section_end "copy_ipxe"
+
+  create_checksums "${_ipxe_output}/"*.{efi,lkrn,pxe}
+}
+
+move_build_artifacts() {
+  print_section_start "move_build_artifacts" "Move build artifacts to release directories"
+
+  mkdir -vp -- "${output}/bootstrap/bootstrap-${version}"
+  mkdir -vp -- "${output}/iso/iso-${version}"
+  mkdir -vp -- "${output}/netboot/netboot-${version}"
+  mv -v -- "${output}/archlinux-bootstrap"* "${output}/bootstrap/bootstrap-${version}/"
+  mv -v -- "${output}/archlinux-"*.iso* "${output}/iso/iso-${version}/"
+  mv -v -- "${output}/${install_dir}/"* "${output}/netboot/netboot-${version}/"
+  rmdir -v "${output}/${install_dir}/"
+
+  print_section_end "move_build_artifacts"
+}
+
+set_ownership() {
+  print_section_start "ownership" "Setting ownership on output"
+
+  if [[ -n "${SUDO_UID:-}" && -n "${SUDO_GID:-}" ]]; then
+    chown -Rv "${SUDO_UID}:${SUDO_GID}" -- "${output}"
+  fi
+
+  print_section_end "ownership"
 }
 
 run_mkarchiso() {
@@ -268,17 +295,10 @@ run_mkarchiso() {
 
   print_section_end "mkarchiso"
 
-  copy_ipxe_binaries
   create_zsync_delta "${output}/"*+(.iso|.tar|.gz|.xz|.zst)
-  create_checksums "${output}/"*+(.iso|.tar|.gz|.xz|.zst) "${output}/ipxe/"*.{efi,lkrn,pxe}
+  create_checksums "${output}/"*+(.iso|.tar|.gz|.xz|.zst)
   create_metrics
-
-  print_section_start "ownership" "Setting ownership on output"
-
-  if [[ -n "${SUDO_UID:-}" && -n "${SUDO_GID:-}" ]]; then
-    chown -Rv "${SUDO_UID}:${SUDO_GID}" -- "${output}"
-  fi
-  print_section_end "ownership"
+  move_build_artifacts
 }
 
 trap cleanup EXIT
@@ -292,3 +312,5 @@ create_ephemeral_pgp_key
 select_codesigning_key
 check_codesigning_cert_validity
 run_mkarchiso
+copy_ipxe_binaries
+set_ownership

README.rst

@@ -4,6 +4,43 @@ releng
 
 This repository is used to create release artifacts for Arch Linux.
 
+Artifacts
+=========
+
+Releases of this repository provide artifacts, that are in either of the following two categories: *build artifacts* and
+*promotion artifacts*. For `archweb <https://github.com/archlinux/archweb/>`_ only releases with *both* artifact types
+are considered.
+
+Build Artifacts
+---------------
+
+These artifacts are the output of the build script in this repository (e.g. by running `make` as root, locally). It
+gathers artifacts by:
+
+- running ``mkarchiso`` (`archiso <https://gitlab.archlinux.org/archlinux/archiso>`_) using the `releng profile
+  <https://gitlab.archlinux.org/archlinux/archiso/-/tree/master/configs/releng>`_ in all available build modes
+  (``bootstrap``, ``iso``, ``netboot``)
+- copying relevant binaries from the `ipxe package <https://archlinux.org/packages/community/x86_64/ipxe/>`_
+- creating a codesigned iPXE target script (see `#9 <https://gitlab.archlinux.org/archlinux/releng/-/issues/9>`_)
+- creating zsync files for large artifacts
+- creating checksums
+
+The artifacts are assembled in a directory structure, that reflects the artifact type (``bootstrap``, ``ipxe``, ``iso``,
+``netboot``) per-release (i.e. ``<type>/<type>-<version>``).
+
+Promotion Artifacts
+-------------------
+
+These artifacts are added to a release by a developer, after it has been created to "promote" the release to become one
+that is used on the mirrors. Promotion artifacts encompass:
+
+- detached PGP signatures for the ``iso`` and ``bootstrap`` build artifacts (see `#1
+  <https://gitlab.archlinux.org/archlinux/releng/-/issues/1>`_)
+- base64-encoded torrent files for the ``iso`` and ``bootstrap`` build artifacts (which include the detached PGP
+  signatures) (see `#5 <https://gitlab.archlinux.org/archlinux/releng/-/issues/5>`_)
+- a JSON file with required metadata for the release (see `#3
+  <https://gitlab.archlinux.org/archlinux/releng/-/issues/3>`_)
+
 Code Signing
 ============