release-pub（发布酒吧）

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.

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