publish-flutter-package

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Publish Flutter Package

发布Flutter包

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

本Skill可通过Git标签触发，自动化Flutter包的发布工作流。

Workflow

工作流

0. Pre-check

0. 预检查

0.1 Project Root

0.1 项目根目录

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.

验证当前工作目录是否为Git仓库的根目录（包含

.git

文件夹和主

pubspec.yaml

文件）。

如果不在根目录（例如，位于子包目录中），建议用户切换到项目根目录后再继续，以确保能正确识别
```
.github/workflows
```
和工作区配置。

0.2 Detect Packages (Workspace Support)

0.2 检测包（支持工作区）

Read the root

pubspec.yaml

file.

Check for the
```
workspace:
```
field.
If present, parse the paths (e.g.,
```
- pkgs/*
```
) to find all nested packages.
Ask the user which package to publish if multiple are detected.

读取根目录下的

pubspec.yaml

文件。

检查是否存在
```
workspace:
```
字段。
如果存在，解析路径（例如
```
- pkgs/*
```
）以找到所有嵌套包。
如果检测到多个包，询问用户要发布哪个包。

1. GitHub Actions Verification

1. GitHub Actions验证

1.1 Configuration Check & Tag Format Discovery

1.1 配置检查与标签格式识别

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.

运行

scripts/inspect_workflows.py [package_name]

来查找并解析发布工作流。

该脚本会返回已识别工作流的JSON列表，包括它们的
```
uses
```
字段和
```
on.push.tags
```
配置。
如果提供了包名称，脚本会根据相关性对工作流进行排序（例如，文件名包含包名称的会优先）。
选择逻辑:
- 验证所选工作流的
```
uses
```
  是否指向
```
dart-lang/setup-dart/.github/workflows/publish.yml
```
  。
- 从
```
tags
```
  列表中提取预期的标签格式（例如
```
v*
```
  ）。
- 如果存在多个工作流，推荐得分最高的工作流并请用户确认。
- 如果用户跳过或未提供替代选项，则使用推荐的工作流继续。
- 如果未找到匹配的工作流，展示Github Action模板并引导用户创建一个。
- 有关自动化发布流程的更多详细信息，请参考自动化发布。

2. Versioning Strategy (SemVer)

2. 版本策略（SemVer）

Use
```
scripts/prepare_release.py <current_version> [--tag-match <pattern>]
```
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.
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.

使用
```
scripts/prepare_release.py <current_version> [--tag-match <pattern>]
```
分析从上一个标签以来的Git历史。
- 如果步骤1.2中获取的标签格式是非标准的（例如
```
package-name-*
```
  ），将其作为
```
--tag-match
```
  参数传入，以确保识别正确的上一个标签。
该脚本会根据提交类型（feat/fix/breaking）提供建议版本，并生成格式化的
```
CHANGELOG.md
```
条目。
向用户展示建议版本和草稿变更日志条目。如果用户跳过或未提供替代选项，则使用建议的值继续。
允许用户在继续前编辑版本或内容。

3. Documentation Updates

3. 文档更新

3.1 pubspec.yaml

Update the

version

field in the relevant package's

pubspec.yaml

with the chosen version.

将选定的版本更新到对应包的

pubspec.yaml

文件的

version

字段中。

3.2 CHANGELOG.md

Insert the confirmed

CHANGELOG.md

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

markdown

undefined

将确认后的

CHANGELOG.md

条目插入到文件顶部（在任何初始标题之后）。格式要求:

markdown

undefined

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

feat/fix/... [important] <content>

注意：如果用户项目有特定的格式约定，请确保格式与之一致，而非仅使用建议的草稿格式。

4. Git Tagging

4. Git打标签

Add a new git tag matching the format found in Step 1.2 using

git tag

Example: If the tag format is
```
v[0-9]+.[0-9]+.[0-9]+
```
, the tag should be
```
v<version>
```
.
Use the exact tag format detected from the workflow file.

使用

git tag

命令添加一个符合步骤1.2中找到的格式的新Git标签。

示例：如果标签格式为
```
v[0-9]+.[0-9]+.[0-9]+
```
，则标签应为
```
v<version>
```
。
必须使用从工作流文件中检测到的精确标签格式。

5. Validation

5. 验证

Run

dart pub publish --dry-run

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.

运行

dart pub publish --dry-run

来验证包的内容和配置。

故障排除：如果发布持续失败或遇到意外问题，请参考官方发布指南获取最新的发布流程和要求。

Resources

资源

scripts/

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

```
inspect_workflows.py
```
：自动发现并解析GitHub Action工作流，以识别发布配置和标签格式。
- 参数：
```
[package_name]
```
```
prepare_release.py
```
：分析Git历史以建议SemVer版本，并生成
```
CHANGELOG.md
```
条目。
- 参数：
```
<current_version>
```
- 可选参数：
```
--tag-match <pattern>
```
  （例如
```
my-pkg-*
```
  或
```
v*
```
  ），用于找到正确的上一个标签。

references/

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

```
github_action_template.md
```
：用于设置发布用GitHub Action的模板。