release-pub Skill

This skill is a specialized release workflow for Dart and Flutter packages published to pub.dev (including Dart CLI tools). It relies on a local helper script (release_helper) to safely manipulate pubspec.yaml and CHANGELOG.md.

Official Documentation

For detailed information on automated publishing, refer to the official Dart documentation: Automated publishing of packages to pub.dev

[!CAUTION] Immutable Tags: NEVER delete, modify, or re-push a Git tag that has already been published to pub.dev. Pub.dev entries are immutable. If a mistake is found after publishing, you must publish a new version (e.g., a patch release) instead of attempting to overwrite the existing tag.

Workflow Overview

Follow these steps precisely:

0. Initial Setup Verification (One-time only)

If this is the first time the package is being published via GitHub Actions, ensure the user has configured OIDC on pub.dev and added the workflow file:

1. Configure pub.dev:

   • Advise the user to access https://pub.dev/packages/<package_name>/admin.
   • Find the Automated publishing section and click Enable publishing from GitHub Actions.
   • Recommend setting the Repository to the current repository (owner/repo).
   • Set the Tag pattern:
     • For single package repositories: v{{version}} (recommended) or {{version}}.
     • For monorepos: package_name-v{{version}}.
   • Security Hardening (Optional but recommended): Mention the Require GitHub Actions environment option to restrict publishing to specific users/approvers via GitHub Deployment Environments.

2. Add GitHub Actions Workflow:

   • Ensure .github/workflows/publish.yml exists with the following content (adjust the tag pattern if necessary):

name: Publish to pub.dev

on:
  push:
    tags:
      - 'v[0-9]+.[0-9]+.[0-9]+*' # Align with the tag-pattern on pub.dev (e.g., 'v{{version}}')

jobs:
  publish:
    permissions:
      id-token: write # Essential for OIDC authentication
    uses: dart-lang/setup-dart/.github/workflows/publish.yml@v1
    # with:
    #   working-directory: path/to/package # Required if the package is not in the root

Wait for the user to confirm the setup is complete before proceeding with the first automated release.

1. Pre-release Checks

• Check if there are any uncommitted changes: git status -s. If there are, tell the user to commit or stash them before proceeding.
• README / Docs Update Check: Scan the recent changes. If there are new features or changed options, remind the user to check if README.md or other documentation needs updating before releasing.
• CRITICAL: Run the appropriate formatter, analyzer, and tests based on the project type:
  • For Dart packages: dart format ., dart analyze, and dart test
  • For Flutter packages: flutter format . (or dart format .), flutter analyze, and flutter test
    • [MANDATORY]: Resolve ALL analyzer issues (errors, warnings, and info level lints) before proceeding. Do not ignore "info" level issues unless they are explicitly documented as unavoidable.
    • If there are unresolved issues, report them and ask the user to fix them (or offer to fix them if they are straightforward).
• CRITICAL: Run the pre-publish dry-run:
  • For Dart packages: dart pub publish --dry-run
  • For Flutter packages: flutter pub publish --dry-run If warnings or errors appear (other than expected ones that can be ignored), report them and ask for user confirmation to proceed.

2. Analyze Changes & Plan Release

• Find the last tag: LAST_TAG=$(git tag --sort=-v:refname | head -1)
• Analyze the commits since the last tag: git log ${LAST_TAG}..HEAD --oneline
• Determine if a tag prefix is used:
  • Check the format of the $LAST_TAG. If it starts with v (e.g., v1.2.3), use v as the prefix for the new tag.
  • If no tags exist (first release), default to using the v prefix (TAG_PREFIX="v").
  • Otherwise, follow the existing pattern (no prefix if $LAST_TAG is just a version string).
• Determine the bump type (major, minor, patch) based on Conventional Commits:
  • BREAKING CHANGE: or <type>!: -> major (or minor if version is < 1.0.0 but follow the user's lead on pre-1.0.0 breaking changes).
  • feat: -> minor
  • fix:, docs:, chore:, refactor:, perf: etc. -> patch
• Generate markdown for CHANGELOG.md notes describing the changes. Generate the notes entirely in English. DO NOT include the ## [version] - [date] title header in the notes as the script adds that automatically.
• Generate Preview (Dry-Run): Present a clear preview of the upcoming release to the user before making any file changes.
  • Show the version bump recommendation (e.g., 1.2.3 -> 1.3.0 (Recommended: feat=minor)) and offer other valid SemVer alternatives (e.g. 1.2.4, 2.0.0) in case they want a different bump.
  • List the categorized commits that will be included in the release.
  • Show the preview text of the upcoming CHANGELOG.md entry.

3. Execution using Helper Script

Use the bundled Dart CLI script to apply changes safely. The script is located at .agents/skills/release-pub/scripts/release_helper.

1. Prepare Release (Version Bump & Changelog): Determine the bump type (major, minor, patch) and the notes as analyzed in Step 2.

   dart run .agents/skills/release-pub/scripts/release_helper/bin/release_helper.dart prepare <type> --notes "
   ### Features
   - ...
   
   ### Bug Fixes
   - ...
   "
   

2. Extract New Version: Read the pubspec.yaml to find the newly updated version string (e.g. 1.2.3). Let's call this $NEW_VERSION.

4. User Confirmation

Ask the user to confirm the prepared release based on the generated preview in Step 2:

• First present the version change options (e.g., "1.3.0 (Recommended)", "1.2.4", "2.0.0").
• Once the user chooses the version, proceed to update the files locally via Step 3.
• After running the execution helpers, show the user the Git diff (git diff) and ask: "Ready to create release commit and tag (v$NEW_VERSION)?" Wait for explicit confirmation.

5. Git & GitHub Operations

Once the user confirms:

1. Stage the files:

   git add pubspec.yaml CHANGELOG.md
   

2. Commit:

   git commit -m "chore: release v$NEW_VERSION"
   

   Note: Do NOT add a Co-Authored-By line. This is a release commit, not a code contribution.
3. Tag:

   git tag ${TAG_PREFIX}$NEW_VERSION
   

4. Push:

   git push origin main
   git push origin ${TAG_PREFIX}$NEW_VERSION
   

5. Create GitHub Release: Save the notes to a temporary file, e.g., /tmp/release_notes.md, then:

   gh release create ${TAG_PREFIX}$NEW_VERSION --title "${TAG_PREFIX}$NEW_VERSION" --notes-file /tmp/release_notes.md
   rm /tmp/release_notes.md
   

Finally, report that the release is complete and that GitHub Actions will automatically handle pushing to pub.dev.