Release Guide

Semantic Versioning

AFFiNE follows semantic versioning. We release patch versions for critical bug fixes, minor versions for new features or non-essential changes, and major versions for any breaking changes.

The current version of AFFiNE is still 0.x, our first stable version is coming soon. The breaking changes may happen before the first stable version released.

Environment

AFFiNE has those environments to deploy node server and release client.

• stable: stable tag version, production database, https://app.affine.pro/
• beta: beta prerelease tag, production database, https://insider.affine.pro/
• canary: canary prerelease tag or nightly deploy, offline database, https://affine.fail/

Deploy Server

The workflow of node server deployment is defined in deploy.yml and the action can be triggered by deploy action. This will deploy our all server once, including:

• api node server (graphql)
• web static server
• sync server

Beta and Stable

Those two environments will use the production database, the deployment action should be careful. So branch deployment here is not supported, only deployment from a tag is accepted. The deloyment steps:

1. create a tag like 0.11.0 or 0.11.0-beta.0 in stable branch
2. push tag to github
3. select tag to deploy

Canary

Manually Deploy

Canary is our testing environment, so deployment to canary is free. We can trigger deployment action manually to canary from any branch or any tag.

• If we select a branch to deploy, the action will generate a nightly version such as 0.11.0-nightly-202401040901-6789da1.
• If we select a tag to deploy, the version will be the tag name without the “v” character starting.

Automatically Deploy

Because the canary is our testing environment, so we will deploy code to it as soon as possible. So we have two automatically deploy logic defined in deploy-automatically.yml.

• When push canary prerelease tag, it will trigger deloyment
• Every day at 09:00 UTC+0 (17:00 UTC+8 Beijing), it will trigger nightly deploy from canary branch

Release Client

The workflow of client release is defined in release-desktop.yml and the action can be triggered by release action. All tag releases can be found in AFFiNE Releases, and all nightly releases can be found in Nightly Releases. The release including:

• macos
• linux
• windows

Beta and Stable

The same as server deployment, release to beta or stable should be careful. So we only accept the tag release. The release steps:

1. create a tag like 0.11.0 or 0.11.0-beta.0 in stable branch
2. push tag to github
3. select tag to release

Canary

Manually Release

The same as server deployment, we can trigger release action manually to canary from any branch or any tag.

• If we select a branch to deploy, the action will generate a nightly version such as 0.11.0-nightly-202401040901-6789da1.
• If we select a tag to deploy, the version will be the tag name without the “v” character starting.

Automatically Release

The same as server deployment, we have two automatically deploy logic defined in release-desktop-automatically.yml.

• When push canary prerelease tag, it will trigger the release action
• Every day at 09:00 UTC+0 (17:00 UTC+8 Beijing), it will trigger nightly release from canary branch

Clients

We have the tag release and nightly release. All tag releases can be found in AFFiNE Releases, and all nightly releases can be found in Nightly Releases. Nightly release can only download manually, can’t upgrade version from client.

Release Note

We release our Apps on GitHub, all production and pre-release Apps can be found at https://github.com/toeverything/AFFiNE/releases. We need a release note for the released version.

A release note should includes:

• overview: An introduction header and a brief overview of the changes, let people know what this version for quickly.
• new features: New features this version includes, it is better to explain the feature design or usage example.
• feature enhancements: The enhancements for released features, maybe some small improvements.
• fixed issues: What issues we fixed in this version, should link the GitHub issues as possible.
• engineering changes: The important changes are not for features or issues directly, such as architecture, or release flow.
• thanks: Introduce the contributions of the people, who are outside the affine team, such as creating GitHub PR, or reporting issues in Discord.

For those contents, we defined Release Note Template, as the template and example for 0.11.3. This release note is from engineer perspective, better for open source, and help to write operation blog.

Reference: https://www.appcues.com/blog/release-notes-examples https://rapidr.io/blog/write-release-notes/#7-great-release-notes-examples https://twitter.com/i/release_notes https://slack.com/intl/en-in/release-notes/ios