mk6i-open-oscar-server/docs/RELEASE.md

Retro AIM Server Release Process

This document explains how the Retro AIM Server release process works.

Overview

Retro AIM Server is built and released to Github using GoReleaser. The release process, which runs from a local computer (and not a CI/CD process) creates pre-built binaries for several platforms (Windows, MacOS, Linux).

GoReleaser runs in a Docker container for two important reasons:

• Docker provides a hermetic environment that prevents build contamination from the host environment.
• The Docker image goreleaser-cross consolidates all the libraries needed for cross-compilation in one place.
  • Given that the application uses cgo, it's much easier to use a pre-built container to build the sqlite library than to manually set up a C compiler on Mac/Windows/Linux etc.

Code Signing Policy

Given the cost and complexity of code signing, this project only distributes unsigned binaries. This means that MacOS distrusts Retro AIM Server by default and quarantines the application when you open it.

If you don't want to bypass this security mechanism, you can build the project yourself instead.

Windows Build Obfuscation

Due to cost and complexity, none of the release artifacts are signed. One consequence of this is that Windows Defender falsely detects the .exe as a virus and auto-quarantines the file upon execution.

We get around this by obfuscating the go binary at built time using garble. In order to accomplish this, the project wraps GoReleaser and garble in a custom Dockerfile Dockerfile.goreleaser.

The GoRelease-garble image must be built locally before running the release process.

Release Procedure

The following is the procedure that builds Retro AIM Server and uploads the build artifacts to a Github release.

1. Build Custom Docker Image

Build the custom GoReleaser Docker image. Ensure that the latest version is set under GO_RELEASER_CROSS_VERSION in the project Makefile.

```sh
make goreleaser-docker
```

1. Export Github Personal Access Token (PAT)

Export a Github Personal Access Token that has write:packages permissions for the Retro AIM Server repo.

```sh
export GITHUB_TOKEN=...
```

1. Tag The Build

Tag the build using semantic versioning.

```shell
git tag v0.1.0
git push --tags
```

1. Dry-Run Release

Execute a dry-run build to make sure all the moving parts work together. Fix any problems that crop up before continuing.

```shell

make release-dry-run

```

1. Release It!

Now run the release process. Once its complete, a new release should appear in Github with download artifacts attached.

```shell

make release

```