Publish Flutter Package

This skill automates the Flutter package release workflow triggered by git tags.

Workflow

0. Pre-check

0.1 Project Root

Verify that the current working directory is the root of the Git repository (contains a .git folder and the main pubspec.yaml).

• If not at the root (e.g., inside a sub-package directory), advise the user to switch to the project root directory before proceeding to ensure .github/workflows and workspace configurations can be correctly identified.

0.2 Detect Packages (Workspace Support)

Read the root pubspec.yaml file.

• Check for the workspace: field.
• If present, parse the paths (e.g., - packages/*) to find all nested packages.
• Ask the user which package to publish if multiple are detected.
• Store the relative path to the selected package (e.g., packages/my_package) for subsequent steps.

0.3 Git & Remote Pre-check

Run scripts/pre_check.py to automatically verify the repository status.

• Uncommitted Changes: If the script reports uncommitted files, list them and ask the user if they want to commit them before proceeding.
• Remote Sync:
  • If the branch is behind the remote, advise the user to git pull before continuing.
  • If the branch is ahead, notify the user that their commits will be pushed in Step 5.
• Ensure the environment is ready for release based on the script's output.

0.4 FVM Detection

Check if the project is using FVM (e.g., presence of .fvm/fvm_config.json).

• If FVM is detected, prefix all subsequent flutter and dart commands with fvm (e.g., use fvm dart instead of dart) to ensure the correct SDK version is used and to avoid environment mismatches.

1. GitHub Actions Verification

1.1 Configuration Check & Tag Format Discovery

Run scripts/inspect_workflows.py [package_name] to find and parse publishing workflows.

• The script returns a JSON list of identified workflows, their uses field, and their on.push.tags.
• If a package name is provided, the script ranks workflows based on relevance (e.g., if the filename contains the package name).
• Selection Logic:
  • Verify that the chosen workflow's uses points to dart-lang/setup-dart/.github/workflows/publish.yml.
  • Extract the expected tag format from the tags list (e.g., v*).
  • If multiple workflows exist, recommend the one with the highest score and ask the user to confirm.
  • If the user skips or provides no alternative, proceed with the recommended workflow.
  • If no matching workflow is found, show the Github Action Template and guide the user to create one.
  • For more details on the automated publishing flow, refer to Automated publishing.

2. Versioning Strategy (SemVer)

• Use scripts/prepare_release.py <current_version> [--tag-match <pattern>] [--package-path <path>] to analyze git history since the last tag.
  • If the tag format from Step 1.2 is non-standard (e.g., package-name-*), pass it as --tag-match to ensure the correct last tag is identified.
  • Pass the relative path of the package (from Step 0.2) as --package-path to filter the git history to only include changes affecting that package.
• This script provides a suggested version based on commit types (feat/fix/breaking) and generates a formatted CHANGELOG.md entry.
• Present the suggestion and the draft changelog entry to the user. If the user skips or provides no alternative, proceed with the suggested values.
• Allow the user to edit the version or the content before proceeding.

3. Documentation Updates

3.1 pubspec.yaml

Update the version field in the relevant package's pubspec.yaml with the chosen version.

3.2 CHANGELOG.md

Insert the confirmed CHANGELOG.md entry at the top of the file (after any initial headers). Format requirement:

## <Version> <YYYY-MM-DD>
* feat/fix/... [**important**] <content>

Note: Ensure the format matches the user's project-specific conventions if they differ from the suggested draft.

4. Git Commit & Validation (Dry Run)

4.1 Git Commit

Commit the modified pubspec.yaml and CHANGELOG.md files:

git add .
git commit -m "chore(release): <version>"

4.2 Validation (Dry Run)

Run dart pub publish --dry-run (or fvm dart pub publish --dry-run if FVM is used) to verify the package contents and configuration.

• Troubleshooting: If publication consistently fails or you encounter unexpected issues, refer to the official publishing guide for the latest release process and requirements.
• Proceed only if the dry run is successful.

5. Git Tagging & Push

Once validated, add a new git tag and push everything to trigger the automated release.

• Tagging: Add a new git tag matching the format found in Step 1.1 using git tag.
  • Example: If the tag format is v[0-9]+.[0-9]+.[0-9]+, the tag should be v<version>.
• Pushing: Use uv run python scripts/push_tag_and_print_actions.py <tag_name> to push the current branch and the new tag to the remote repository.
  • The script will:
    • run git push
    • run git push origin <tag_name>
    • print https://github.com/<owner>/<repo>/actions after the tag push succeeds, so the user can jump directly to the workflow run page
  • If the repository remote cannot be parsed as a GitHub repository, explicitly tell the user that the Actions URL could not be derived automatically.

Resources

scripts/

• pre_check.py: Automatically verifies uncommitted changes and remote branch synchronization status before starting the release process.
  • Returns a JSON report of the current git status.
• inspect_workflows.py: Automatically discovers and parses GitHub Action workflows to identify publishing configurations and tag formats.
  • Arguments: [package_name]
• prepare_release.py: Analyze git history to suggest SemVer version and generate CHANGELOG.md entry.
  • Arguments: <current_version>
  • Optional: --tag-match <pattern> (e.g., my-pkg-* or v*) to find the correct previous tag.
  • Optional: --package-path <path> (e.g., packages/my_pkg) to filter changes by package directory.
• push_tag_and_print_actions.py: Push the current branch and release tag, then print the GitHub Actions page URL for the repository.
  • Arguments: <tag_name>

references/

• github_action_template.md: A template for setting up the GitHub Action for publishing.