# Release Workflow

This document describes the release workflow for the Solarus project.

* [Prerequisites](#prerequisites)
* [Repository Preparation](#repository-preparation)
* [Package Files Upload](#package-files-upload)
* [Release Creation](#release-creation)
* [Package Naming Convention](#package-naming-convention)
* [Appendix](#appendix)

## Prerequisites

Instructions in this document require the Solarus [releaser script](tools/releaser.sh) and its
dependencies (`jq`, `curl`, `mktemp` and `unzip`) to be available in the local machine.

A GitLab API access token for the [`@solarus-labs`](https://gitlab.com/solarus-labs/) automation
account is also required. The token must be exported in the `GITLAB_TOKEN` environment variable.
It is recommended to store the token in a secured file and export it as follows:
```
export GITLAB_TOKEN=$(< /path/to/file-with-token)
```

## Repository Preparation

Refer to the [repository management](repository.md) guide for details about branching and tagging.

* Create a new release branch for the new release, for example `release-2.0.0`.
* If necessary, work final details for the release in the newly created branch.
* When satisfied, merge the release branch into the `master` branch.
* Create a new tag for the release, for example `v2.0.0` from the `master` branch.
* Ensure that all the above is pushed to the remote in GitLab for the CI/CD pipeline to start.
* Wait for the CI/CD pipeline to completely finish and succeed.
* Proceed to the [package files upload](#package-files-upload) section.

## Package Files Upload

After the [repository preparation](#repository-preparation) is completed, package files for the
release must be uploaded to the [package registry](https://gitlab.com/solarus-games/solarus/-/packages)
of the Solarus repository to be used as release assets.

Package files can be created either by CI/CD pipeline jobs or manually in a local machine.

* Ensure that the [prerequisites](#prerequisites) are met in the local machine.
* Create a local directory for storing all the release files, for example `release-2.0.0/`.
* Download artifacts generated by CI/CD pipeline jobs for the release tag, for example `v2.0.0`:
  ```
  releaser.sh job download-artifact v2.0.0 mingw-x64-package release-2.0.0/
  ```
* Add additional package files created manually in a local machine to the release directory.
  * Make sure to follow the established [package naming convention](#package-naming-convention).
  * For example, a macOS launcher package: `release-2.0.0/solarus-launcher-v2.0.0-macos-arm64.dmg`
* Upload all package files in the release directory to the GitLab generic package registry:
  ```
  releaser.sh package upload 2.0.0 release-2.0.0/*.zip release-2.0.0/*.dmg
  ```
* Proceed to the [release creation](#release-creation) section.

## Release Creation

After the [package files upload](#package-files-upload) is completed, a
[release](https://gitlab.com/solarus-games/solarus/-/releases) in the Solarus repository can be
created with assets linked from the package registry.

* Create notes for the release using [GitLab Markdown](https://docs.gitlab.com/ee/user/markdown/).
  * An example release notes file can be found in the [appendix](#appendix).
  * Save the notes into a file in the release directory, for example `release-2.0.0/notes.md`.
* Create the release providing the notes file created above (all package files uploaded to the
  package registry for the specified version will be used as asset links for the release):
  ```
  releaser.sh release create 2.0.0 release-2.0.0/notes.md
  ```
* The release is now available in: <https://gitlab.com/solarus-games/solarus/-/releases/v2.0.0>

## Package Naming Convention

All package file names must adhere to the following naming convention:
```
NAME-VERSION-PLATFORM-ARCH.EXT
```

Where each component is defined as follows:

* `NAME`: The base name of the package. See below for supported Solarus packages.
* `VERSION`: The version of the package, including the `v` prefix. For example: `v2.0.0`.
* `PLATFORM`: The system platform of the package. See below for supported platforms.
* `ARCHITECTURE`: The CPU architecture of the package. See below for supported architectures.
* `EXT`: The package file extension, depending on its type. See below for supported extensions.

Current list of supported Solarus packages:

* `solarus`: Contains all components: engine library, editor, launcher and CLI runner tool.
* `solarus-cli`: Contains components without GUI: engine library and CLI runner tool.
* `solarus-launcher`: Contains components for players: engine library and launcher.

Current list of supported platforms:

* `windows`: Microsoft Windows operating system.
* `macos`: Apple macOS operating system.

Current list of supported architectures:

* `arm64`: AArch64 64-bit ARM architecture family.
* `x64`: x86-64 64-bit architecture family (also known as AMD64 and Intel 64).

Current list of supported extensions:

* `zip`: Simple ZIP-compressed package containing all needed files.
* `dmg`: Apple disk image file containing the application.

## Appendix

Example release notes file for version `v2.0.0`:
```markdown
## Solarus 2.0.0 (2025-04-01)

The multiplayer and dark mode update is finally here!

* Watch the [release trailer](https://www.youtube.com/watch?v=X_hJDhWXxU8) for details.
* New [documentation website](https://docs.solarus-games.org/) available.
* Visit the [Solarus Games website](https://solarus-games.org/) for more information.

Changelog: <https://gitlab.com/solarus-games/solarus/-/blob/v2.0.0/changelog.md?ref_type=tags>
```

Example session when performing the release for version `v2.0.0`:
```
$ export GITLAB_TOKEN=$(< /path/to/file-with-token)

$ tools/releaser.sh job download-artifact v2.0.0 mingw-x64-package release-2.0.0/
Archive:  /tmp/tmp.BmUDuIVNxi/artifact.zip
  inflating: release-2.0.0/solarus-cli-v2.0.0-windows-x64.zip

$ ls -1 release-2.0.0/
notes.md
solarus-cli-v2.0.0-windows-x64.zip
solarus-launcher-v2.0.0-macos-arm64.dmg
solarus-launcher-v2.0.0-windows-x64.zip
solarus-v2.0.0-windows-x64.zip

$ tools/releaser.sh package upload 2.0.0 release-2.0.0/*.zip release-2.0.0/*.dmg
uploading file for generic package solarus/2.0.0: release-2.0.0/solarus-cli-v2.0.0-windows-x64.zip
{"message":"201 Created"}
uploading file for generic package solarus/2.0.0: release-2.0.0/solarus-launcher-v2.0.0-windows-x64.zip
{"message":"201 Created"}
uploading file for generic package solarus/2.0.0: release-2.0.0/solarus-v2.0.0-windows-x64.zip
{"message":"201 Created"}
uploading file for generic package solarus/2.0.0: release-2.0.0/solarus-launcher-v2.0.0-macos-arm64.dmg
{"message":"201 Created"}

$ tools/releaser.sh release create 2.0.0 release-2.0.0/notes.md
release created: v2.0.0 (1c69f3d7ec133eaff28c22d756170eba69a520b0)
```
