# 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.
# -c defaults to git HEAD.
# -g default to current Guix describe output.
./etc/tag-release.scm vYYYYMMDD [-c GUIX-SCIENCE-COMMIT] [-g GUIX-COMMIT]
# 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
```