Version

Version Bump Skill

Trigger

Use this skill when the user types /version <major|minor|patch>.

Overview

This skill automates the version bump workflow for the paperless-mobile Flutter app. It:

1. Reads and bumps the semantic version in pubspec.yaml
2. Increments the build number by 10
3. Collects feat and fix commits since the latest git tag and generates human-readable release notes in English
4. Discovers available locale directories under android/fastlane/metadata/android/, writes the English notes for en-US, and translates them for each additional locale
5. Registers the new Android version code in _versionNumbers inside changelog_dialog.dart

Version Format

The version field in pubspec.yaml follows the format:

<major>.<minor>.<patch>+<buildNumber>

Example: 4.0.3+570

The Android version code used for release artifacts and file naming is derived by appending 3 to the build number:

androidVersionCode = "<buildNumber>3"

For example, build number 570 → Android version code 5703.

Step-by-Step Workflow

Step 1: Parse the Current Version

Read pubspec.yaml and extract the version field:

version: <major>.<minor>.<patch>+<buildNumber>

Use grep "^version:" pubspec.yaml or read the file directly.

Step 2: Compute the New Version

Based on the argument provided by the user (major, minor, or patch):

• patch: increment the patch number, keep major and minor. Reset nothing.
  • e.g. 4.0.3 → 4.0.4
• minor: increment the minor number, reset patch to 0.
  • e.g. 4.0.3 → 4.1.0
• major: increment the major number, reset minor and patch to 0.
  • e.g. 4.0.3 → 5.0.0

Always increment the build number by exactly 10, regardless of bump type:

• e.g. 570 → 580

The new version string becomes:

<newMajor>.<newMinor>.<newPatch>+<newBuildNumber>

Step 3: Compute the New Android Version Code

newAndroidVersionCode = "<newBuildNumber>3"

Example: build number 580 → Android version code 5803.

Step 4: Update pubspec.yaml

Replace the old version line with the new one. Use replace_string_in_file on the exact line:

version: <old_version_string>

→

version: <new_version_string>

Step 5: Collect Commits and Generate Release Notes

Run the following command to find the latest git tag and list all feat and fix commits since then:

git log $(git describe --tags --abbrev=0)..HEAD --oneline

From the output, filter only lines that start with feat or fix (conventional commit format). Ignore all other types (chore, refactor, docs, test, ci, build, etc.).

For each matching commit, rewrite the message as a short, plain-language bullet point suitable for end users:

• Remove the conventional commit prefix (feat:, fix:, feat(scope):, etc.)
• Remove technical jargon, references to internal code names, function names, or file names
• Describe what the user can now do or what problem was fixed, not how it was implemented
• Keep each bullet to one sentence, starting with a capital letter, no trailing period

Compile the results into a bulleted list, for example:

- Documents can now be filtered by custom fields
- Fixed a crash when opening the document scanner on some devices

If no feat or fix commits are found, fall back to the placeholder content:

-

Step 6: Create Fastlane Changelog Files

6a: Discover locales

List the available locale directories under android/fastlane/metadata/android/. Each subdirectory name is a locale code (e.g. en-US, de-DE). Use:

ls android/fastlane/metadata/android/

Treat en-US as the primary locale. All other locale directories are secondary locales that require translation.

6b: Write the English changelog

Create android/fastlane/metadata/android/en-US/changelogs/<newAndroidVersionCode>.txt with the English bullet list generated in Step 5.

6c: Translate and write each secondary locale

For each secondary locale directory (e.g. de-DE), translate the English bullet list into that locale's language. Apply the same rules as Step 5 when translating:

• Plain, friendly language suitable for end users
• One sentence per bullet, starting with a capital letter, no trailing period
• Preserve the - prefix on each line

Create android/fastlane/metadata/android/<locale>/changelogs/<newAndroidVersionCode>.txt with the translated content.

If no feat or fix commits were found (placeholder fallback), write the same - placeholder for all locales without translating.

Step 6: Register the New Version in _versionNumbers

In lib/features/changelogs/view/changelog_dialog.dart, add a new entry at the top of the _versionNumbers map.

The current top entry looks like:

const _versionNumbers = {
  "<oldAndroidVersionCode>": "<oldSemanticVersion>",

Replace it with:

const _versionNumbers = {
  "<newAndroidVersionCode>": "<newSemanticVersion>",
  "<oldAndroidVersionCode>": "<oldSemanticVersion>",

Where:

• newAndroidVersionCode = <newBuildNumber>3 (e.g., "5803")
• newSemanticVersion = new semantic version string (e.g., "4.0.4")

Step 7: Report the Result

After completing all changes, summarize what was done:

Bumped version: <oldVersion> → <newVersion>
Build number:   <oldBuild> → <newBuild>
Android code:   <oldAndroidCode> → <newAndroidCode>

Release notes:
<generated bullet list, or "No feat/fix commits found." if empty>

Files updated:
- pubspec.yaml
- lib/features/changelogs/view/changelog_dialog.dart
- android/fastlane/metadata/android/en-US/changelogs/<newAndroidCode>.txt (created)
- android/fastlane/metadata/android/<locale2>/changelogs/<newAndroidCode>.txt (created, translated)
- ... (one entry per discovered locale)

Example

Given current version: 4.0.3+570 and argument patch, with two relevant commits since the last tag:

• New semantic version: 4.0.4
• New build number: 580
• New Android version code: 5803
• New pubspec version line: version: 4.0.4+580
• Generated release notes (from feat/fix commits):

  - Documents can now be filtered by custom fields
  - Fixed a crash when opening the document scanner on some devices
  

• Discovered locale dirs: en-US, de-DE (example)
• New changelog files:
  • en-US/changelogs/5803.txt — English notes as generated
  • de-DE/changelogs/5803.txt — German translation of the same notes
• New _versionNumbers entry: "5803": "4.0.4"

Important Notes

• The _versionNumbers map is const at the bottom of changelog_dialog.dart.
• Always insert the new entry as the first entry in the map (top of the list).
• Only feat and fix conventional commit types are included in release notes. All other types (chore, refactor, docs, test, ci, build, etc.) are ignored.
• Rewrite commit messages in plain language for end users — avoid technical terms, scope tags, issue references, and code names.
• If no qualifying commits are found, fall back to the - placeholder in all changelog files (no translation needed).
• Always discover locale directories at runtime — do not hardcode locale codes.
• en-US is always the primary locale. Every other locale directory receives a translated version of the English notes.
• Never guess the version; always read it fresh from pubspec.yaml before computing.