3 files changed, 175 insertions, 0 deletions

diff --git a/.forgejo/workflows/publish-release.yml b/.forgejo/workflows/publish-release.yml
new file mode 100644
index 0000000..5a7dcd6
--- /dev/null
+++ b/.forgejo/workflows/publish-release.yml
@@ -0,0 +1,25 @@
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  publish-release:
+    name: Publishes the `channels.scm` file for a Guix-Science release.
+    runs-on: guix
+    steps:
+     - run: |
+         set -e
+         set -x
+         set -o pipefail
+         TAG=$GITHUB_REF_NAME
+         # Clone full repository to get all tags (shallow cloning would skip some tags).
+         guix shell git-minimal nss-certs -CN -- git clone --tags $GITHUB_SERVER_URL/$GITHUB_REPOSITORY repo
+         cd repo
+         # Extract the 'channels.scm' contents from the tag's message (filtering out the header and the signature).
+         guix shell git-minimal -C -- git show $TAG --format=%N --no-patch | tail -n +4 | head -n -15  > channels.scm
+         # Create a release using the API, JSON data is stored in a file to prevent issues with mixing quotes
+         echo "{\"tag_name\": \"$TAG\", \"hide_archive_links\": true}" > json-data
+         RELEASE_ID=$(guix shell -CN curl nss-certs -- curl -H 'Content-Type: application/json' -d @json-data "$GITHUB_API_URL/repos/$GITHUB_REPOSITORY/releases?token=${{ secrets.TOKEN }}" | guix shell -C jq -- jq -r '.id')
+         # Add the channels file to the release
+         # TODO: verify request status.
+         guix shell -CN curl nss-certs -- curl -H 'accept: application/json' -H 'Content-Type: multipart/form-data' -F 'attachment=@channels.scm' --request POST "$GITHUB_API_URL/repos/$GITHUB_REPOSITORY/releases/$RELEASE_ID/assets?name=channels.scm&token=${{ secrets.TOKEN }}"
\ No newline at end of file
diff --git a/documentation/release.md b/documentation/release.md
new file mode 100644
index 0000000..cad69c3
--- /dev/null
+++ b/documentation/release.md
@@ -0,0 +1,101 @@
+# Release process for the Guix-Science channel #
+
+## Introduction
+
+A "release of the Guix-Science channel" is a Guix-Science commit
+associated to a Guix revision against which the channel is guaranteed
+to build.
+
+A "release of the Guix-Science channel" is done by:
+  * tagging a specific commit of the repository, the tag name being
+    formatted as `vYYYYMMDD`, with a tag annotation described in the
+    next section,
+  * generating the corresponding `channels-YYYYMMD.scm` file with
+    pinned revisions for both the Guix and the Guix-Science channels,
+    using the commits above,
+  * providing the `channels-YYYYMMDD.scm` file in the Releases space
+    of the Codeberg repository.
+
+## Tag message format
+
+The tag message should embed the full `channels.scm` file content,
+which would include some metadata in the form of Scheme comments at
+the beginning of the message:
+  * first line should contain the Guix-Science release,
+  * second line should contain a blank line,
+  * third line should contain the Guix revision,
+  * the rest of the message should contain the corresponding list of
+    channels as a Guile object.
+
+Below is an example for the message that would be included in tag
+`v20260304` for a Guix-Science release at revision
+`8c2f79e97cff0003a0fcbab2e3bc4267d48c116c` against Guix revision
+`259643c993c6bba89a66da3b84329dd2e1dc439d`:
+
+```scheme
+;; Guix-Science release v20260304
+;;
+;; Guix revision: 259643c993c6bba89a66da3b84329dd2e1dc439d
+(list (channel
+        (name 'guix-science)
+        (url "https://codeberg.org/guix-science/guix-science.git")
+        (branch "master")
+        (commit
+          "8c2f79e97cff0003a0fcbab2e3bc4267d48c116c")
+        (introduction
+          (make-channel-introduction
+            "b1fe5aaff3ab48e798a4cce02f0212bc91f423dc"
+            (openpgp-fingerprint
+              "CA4F 8CF4 37D7 478F DA05  5FD4 4213 7701 1A37 8446"))))
+      (channel
+        (name 'guix)
+        (url "https://git.guix.gnu.org/guix.git")
+        (branch "master")
+        (commit
+          "259643c993c6bba89a66da3b84329dd2e1dc439d")
+        (introduction
+          (make-channel-introduction
+            "9edb3f66fd807b096b48283debdcddccfea34bad"
+            (openpgp-fingerprint
+              "BBB0 2DDF 2CEA F6A8 0D1D  E643 A2A0 6DF2 A33A 54FA")))))
+
+```
+
+## Tagging a release
+
+A specific commit should be tagged using the script provided in the
+`./etc` directory at the root of the Guix-Science repository:
+
+```shell
+# Create the tag in the local checkout.
+sh ./etc/tag-release.sh vYYYYMMDD <guix-science-commit> <guix-revision>
+# Push the tag to the remote.
+git push --tags
+```
+
+After pushing the new tag to the remote repository, the Forgejo action
+defined in `publish-release.yml` will be executed, effectively
+creating a new entry in the Releases section of the Guix-Science
+repository, with the corresponding `channels.scm` file available for
+download.
+
+## Retrieving the Guix revision information manually from the tag
+
+In order to print the Guix revision information embedded with the tag,
+the following command can be issued:
+
+```shell
+git show vYYYYMMDD --format=%N --no-patch | awk '/;; Guix revision/ {print $4}'
+```
+
+## Retrieving the `channels.scm` information embedded in the tag
+
+The `channels.scm` file content corresponding to the `vYYYYMMDD` tag
+can be retrieved with the following command:
+
+```shell
+# This will print the information on screen. Redirect it to a file
+# by appending e.g. "> channels.scm" at the end of the command.
+git show vYYYYMMDD --format=%N --no-patch | tail -n +4 | head -n -15
+```
+
diff --git a/etc/tag-release.sh b/etc/tag-release.sh
new file mode 100644
index 0000000..d9b4a21
--- /dev/null
+++ b/etc/tag-release.sh
@@ -0,0 +1,49 @@
+#!/bin/sh
+
+set -e
+set -o pipefail
+
+TAG="$1"
+GUIX_SCIENCE_COMMIT="$2"
+GUIX_REVISION="$3"
+
+usage () {
+    echo "usage: $0 <release-tag> <guix-science-commit> <guix-revision>"
+    echo
+    echo "where <release-tag> is in the format vYYYYMMDD, <guix-science-commit>"
+    echo "is the Guix-Science commit to tag and <guix-revision> is the Guix"
+    echo "revision to associate with the release."
+}
+
+# TODO: check arguments.
+if [ $# -ne 3 ] ; then
+    usage
+    exit 1
+fi
+
+echo ";; Guix-Science release $TAG
+;;
+;; Guix revision: $GUIX_REVISION
+(list (channel
+        (name 'guix-science)
+        (url \"https://codeberg.org/guix-science/guix-science.git\")
+        (branch \"master\")
+        (commit
+          \"$GUIX_SCIENCE_COMMIT\")
+        (introduction
+          (make-channel-introduction
+            \"b1fe5aaff3ab48e798a4cce02f0212bc91f423dc\"
+            (openpgp-fingerprint
+              \"CA4F 8CF4 37D7 478F DA05  5FD4 4213 7701 1A37 8446\"))))
+      (channel
+        (name 'guix)
+        (url \"https://git.guix.gnu.org/guix.git\")
+        (branch \"master\")
+        (commit
+          \"$GUIX_REVISION\")
+        (introduction
+          (make-channel-introduction
+            \"9edb3f66fd807b096b48283debdcddccfea34bad\"
+            (openpgp-fingerprint
+              \"BBB0 2DDF 2CEA F6A8 0D1D  E643 A2A0 6DF2 A33A 54FA\")))))
+" | git tag --annotate --sign -F - $TAG $GUIX_SCIENCE_COMMIT