Release

Amarok Release Procedure

You are preparing a new release for Amarok. Follow the steps below in order, asking for user confirmation at each decision point. Do not skip steps.

Step 1: Determine release type and version

1. Find the current version in app/build.gradle (versionCode and versionName).
2. Read git log since the last tag to understand what changed.
3. Ask the user: stable or beta? Present both options with their proposed version name and code:
   • Stable: use the versioning rules below to propose a version.
   • Beta: use the versioning rules below to propose a version.
4. Versioning rules for computing the proposed version:
   • First beta of new cycle: bump minor version from the current stable (e.g., 0.10.0 → 0.11.0-beta1), round versionCode up to next multiple of 10 (e.g., 124 → 130).
   • Subsequent beta: increment beta number (e.g., -beta1 → -beta2), increment versionCode by 1.
   • Stable release (from beta): drop the beta suffix, increment versionCode by 1.
   • Stable patch release: bump patch version (e.g., 0.10.0 → 0.10.1), increment versionCode by 1.

Step 2: Merge open translation PRs (stable releases only)

For stable releases only:

1. List open PRs from the Weblate bot using: GITHUB_TOKEN=<token> gh pr list -R deltazefiro/Amarok-Hider --search "translation"
2. If translation PRs exist, show them to the user.
3. IMPORTANT: Tell the user to merge the selected PRs on GitHub directly (using squash merge), then wait for them to confirm. Do NOT merge locally — GitHub's squash merge preserves the correct commit message format with per-language (by Name <email>) lines that the translation credit script depends on.
4. After user confirms the PRs are merged on GitHub, run git pull origin main to pull them in.
5. If no translation PRs are found, inform the user and move on.

Step 3: Verify prerequisites

1. Confirm git working tree is clean (git status --short should be empty). If not, ask user to resolve.
2. Build the app: ./gradlew assemble (timeout 300s). If it fails, stop and report the error.

Step 4: Bump version in gradle

Edit app/build.gradle to update versionCode and versionName to the values confirmed in Step 1.

Step 5: Draft release notes

5a: Gather changes

1. Run git log <last-tag>..HEAD --oneline --no-merges to get the full commit list.
2. Focus on user-facing changes only — skip technical details, refactors, docs, CI, etc.
3. Consolidate related changes: if a feature was introduced and subsequent commits fix issues with that same feature within this release range, only mention the feature — not the fixes.

5b: Generate translation credits (if translation commits exist in range)

Run:

GITHUB_TOKEN=<token> python3 .github/scripts/summarize_translation_contrib.py --start <last-tag> --end HEAD

If the script requires a GitHub token and one hasn't been provided yet, ask the user for it. Store it for later use in Step 7.

5c: Write fastlane changelog

Create fastlane/metadata/android/en-US/changelogs/<versionCode>.txt following this format:

v<versionName>
- Change 1
- Change 2 (#issue)
...

• English only, concise, no longer than 200 words.
• Do not include translation update details in fastlane changelog.
• Match the style of existing changelogs (check previous files in the same directory).

5d: Write GitHub release draft

Create tmp/release_note_v<versionName>.md following the format below.

For stable releases:

## ChangeLog

- Feature or fix description (#issue)
- <translation credit line from script>

> The `@username` credits are generated by a [script](https://github.com/deltazefiro/Amarok-Hider/blob/main/.github/scripts/summarize_translation_contrib.py) based on your Weblate email. If you notice any mistakes, please open an issue.

## 更新内容

- Chinese translation of each changelog item
- 更新社区翻译（详见上文）

**Full Changelog**: https://github.com/deltazefiro/Amarok-Hider/compare/<last-tag>...v<versionName>

## 下载版本说明 / Which version should I download?

- **First time install** / 首次安装：
  → Use the version without any suffix / 请下载「无后缀」版本
- **Updating** / 升级已有安装：
  - Installed from _F-Droid_ or _IzzyOnDroid_ / 原先通过 F-Droid 或 IzzyOnDroid 安装：
    → Use the version with `-foss` suffix / 请下载带 `-foss` 后缀的版本
  - Installed from _Coolapk_, _GitHub_, _AppCenter_ or other channels / 原先通过酷安、AppCenter、GitHub 或其他渠道安装：
    → Use the version without suffix / 请下载「无后缀」版本

For beta releases, prepend this warning block before the ChangeLog:

> [!warning]
> This is a pre-release version. Get the latest stable release [here](https://github.com/deltazefiro/Amarok-Hider/releases/latest/).
> 这是一个不稳定预览版本。请在[这里](https://github.com/deltazefiro/Amarok-Hider/releases/latest/)下载最新的稳定版本。

Omit the translation credit section and its note in beta releases.

5e: Ask user to review

Tell the user to review both files. Wait for confirmation before proceeding.

Step 6: Commit, tag, and push

1. Stage app/build.gradle and the fastlane changelog file.
2. Commit with message: chore: Bump version to v<versionName> (<versionCode>)
3. Create git tag: git tag v<versionName>
4. Push: git push origin main --tags

Step 7: Create GitHub release draft

Ask the user for their GitHub token if not already obtained.

GITHUB_TOKEN=<token> gh release create v<versionName> \
  -R deltazefiro/Amarok-Hider \
  --title "Amarok v<versionName>" \
  --notes-file tmp/release_note_v<versionName>.md \
  --draft \
  <if beta: --prerelease>

Report the release URL to the user. Remind them to review and publish when ready