`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:

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.
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.

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
- ...
"

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:

Stage the files:
```
git add pubspec.yaml CHANGELOG.md
```
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.
Tag:
```
git tag ${TAG_PREFIX}$NEW_VERSION
```

Push:

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

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.

release-pub

release-pub Skill