Enhance release workflow with auto-release on merge and PR validation
Co-authored-by: Fu-Jie <33599649+Fu-Jie@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
@@ -1,197 +1,189 @@
|
||||
# Plugin Release Workflow / 插件发布工作流
|
||||
# Plugin Release Workflow
|
||||
|
||||
This document describes the workflow for releasing plugin updates.
|
||||
|
||||
本文档描述了发布插件更新的工作流程。
|
||||
|
||||
---
|
||||
|
||||
## Overview / 概述
|
||||
## Overview
|
||||
|
||||
The release workflow consists of the following components:
|
||||
|
||||
发布工作流包含以下组件：
|
||||
|
||||
1. **CHANGELOG.md** - Records all notable changes / 记录所有重要更改
|
||||
2. **Version Extraction Script** - Automatically extracts plugin versions / 自动提取插件版本
|
||||
3. **GitHub Actions Workflows** - Automates the release process / 自动化发布流程
|
||||
1. **CHANGELOG.md** - Records all notable changes
|
||||
2. **Version Extraction Script** - Automatically extracts plugin versions
|
||||
3. **GitHub Actions Workflows** - Automates the release process
|
||||
|
||||
---
|
||||
|
||||
## Release Process / 发布流程
|
||||
## Automatic Release Process ⭐
|
||||
|
||||
### Step 1: Update Plugin Version / 更新插件版本
|
||||
When a plugin update PR is merged to `main` branch, the release process is **triggered automatically**:
|
||||
|
||||
When you make changes to a plugin, update the version number in the plugin's docstring:
|
||||
### PR Merge Requirements
|
||||
|
||||
当您对插件进行更改时，更新插件文档字符串中的版本号：
|
||||
PRs that modify plugin files must meet the following conditions to merge:
|
||||
|
||||
1. ✅ **Version must be updated** - The plugin's `version` field must be changed
|
||||
2. ✅ **PR description must contain update notes** - At least 20 characters of description
|
||||
|
||||
If these conditions are not met, the PR check will fail and cannot be merged.
|
||||
|
||||
### Automatic Release Contents
|
||||
|
||||
After successful merge, the system will automatically:
|
||||
|
||||
1. 🔍 Detect version changes (compared to last release)
|
||||
2. 📝 Generate release notes (with update content and commit history)
|
||||
3. 📦 Create GitHub Release (with downloadable plugin files)
|
||||
4. 🏷️ Auto-generate version number (format: `vYYYY.MM.DD-run_number`)
|
||||
|
||||
### Release Includes
|
||||
|
||||
- **plugins_release.zip** - All updated plugin files packaged
|
||||
- **plugin_versions.json** - All plugin version information (JSON format)
|
||||
- **Release Notes** - Includes:
|
||||
- List of new/updated plugins
|
||||
- Related commit history
|
||||
- Complete plugin version table
|
||||
- Installation instructions
|
||||
|
||||
---
|
||||
|
||||
## Release Process
|
||||
|
||||
### Step 1: Update Plugin Version
|
||||
|
||||
When you make changes to a plugin, you **must** update the version number:
|
||||
|
||||
```python
|
||||
"""
|
||||
title: My Plugin
|
||||
author: Fu-Jie
|
||||
version: 0.2.0 # <- Update this / 更新这里
|
||||
version: 0.2.0 # <- Must update this!
|
||||
...
|
||||
"""
|
||||
```
|
||||
|
||||
### Step 2: Update CHANGELOG / 更新更新日志
|
||||
### Step 2: Create PR with Update Notes
|
||||
|
||||
Add your changes to the `[Unreleased]` section in `CHANGELOG.md`:
|
||||
|
||||
在 `CHANGELOG.md` 的 `[Unreleased]` 部分添加您的更改：
|
||||
Add update notes in your PR description (at least 20 characters):
|
||||
|
||||
```markdown
|
||||
## [Unreleased] / 未发布
|
||||
## Changes
|
||||
|
||||
### Added / 新增
|
||||
- New feature in Smart Mind Map / 智能思维导图新功能
|
||||
|
||||
### Changed / 变更
|
||||
- Improved performance / 性能优化
|
||||
|
||||
### Fixed / 修复
|
||||
- Fixed bug in export / 修复导出 bug
|
||||
- Added XXX feature
|
||||
- Fixed YYY issue
|
||||
- Improved ZZZ performance
|
||||
```
|
||||
|
||||
### Step 3: Create a Release / 创建发布
|
||||
### Step 3: Merge PR
|
||||
|
||||
#### Option A: Manual Release (Recommended) / 手动发布（推荐）
|
||||
After checks pass, merge the PR to `main` branch - the system will automatically create a Release.
|
||||
|
||||
---
|
||||
|
||||
## Manual Release (Optional)
|
||||
|
||||
In addition to automatic release, you can also trigger manually:
|
||||
|
||||
### Option A: Manual Trigger
|
||||
|
||||
1. Go to GitHub Actions → "Plugin Release / 插件发布"
|
||||
2. Click "Run workflow"
|
||||
3. Fill in the details:
|
||||
- **version**: e.g., `v1.0.0`
|
||||
- **version**: e.g., `v1.0.0` (leave empty for auto-generation)
|
||||
- **release_title**: e.g., "Smart Mind Map Major Update"
|
||||
- **release_notes**: Additional notes in Markdown
|
||||
- **prerelease**: Check if this is a pre-release
|
||||
|
||||
1. 前往 GitHub Actions → "Plugin Release / 插件发布"
|
||||
2. 点击 "Run workflow"
|
||||
3. 填写详细信息：
|
||||
- **version**: 例如 `v1.0.0`
|
||||
- **release_title**: 例如 "智能思维导图重大更新"
|
||||
- **release_notes**: Markdown 格式的附加说明
|
||||
- **prerelease**: 如果是预发布版本则勾选
|
||||
|
||||
#### Option B: Tag-based Release / 基于标签的发布
|
||||
### Option B: Tag-based Release
|
||||
|
||||
```bash
|
||||
# Create and push a version tag / 创建并推送版本标签
|
||||
# Create and push a version tag
|
||||
git tag -a v1.0.0 -m "Release v1.0.0"
|
||||
git push origin v1.0.0
|
||||
```
|
||||
|
||||
This will automatically trigger the release workflow.
|
||||
|
||||
这将自动触发发布工作流。
|
||||
|
||||
### Step 4: Finalize CHANGELOG / 完成更新日志
|
||||
|
||||
After the release, move the `[Unreleased]` content to a new version section:
|
||||
|
||||
发布后，将 `[Unreleased]` 的内容移动到新的版本部分：
|
||||
|
||||
```markdown
|
||||
## [Unreleased] / 未发布
|
||||
<!-- Empty for now / 暂时为空 -->
|
||||
|
||||
## [1.0.0] - 2024-01-15
|
||||
|
||||
### Added / 新增
|
||||
- New feature in Smart Mind Map
|
||||
|
||||
### Plugin Updates / 插件更新
|
||||
- `Smart Mind Map`: v0.7.0 → v0.8.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Version Numbering / 版本编号
|
||||
## Version Numbering
|
||||
|
||||
We follow [Semantic Versioning](https://semver.org/):
|
||||
|
||||
我们遵循[语义化版本](https://semver.org/lang/zh-CN/)：
|
||||
- **MAJOR**: Breaking changes
|
||||
- **MINOR**: New features, backwards compatible
|
||||
- **PATCH**: Bug fixes
|
||||
|
||||
- **MAJOR (主版本)**: Breaking changes / 不兼容的变更
|
||||
- **MINOR (次版本)**: New features, backwards compatible / 新功能，向后兼容
|
||||
- **PATCH (补丁版本)**: Bug fixes / Bug 修复
|
||||
### Examples
|
||||
|
||||
### Examples / 示例
|
||||
|
||||
| Change Type / 变更类型 | Version Change / 版本变化 |
|
||||
|----------------------|--------------------------|
|
||||
| Bug fix / Bug 修复 | 0.1.0 → 0.1.1 |
|
||||
| New feature / 新功能 | 0.1.1 → 0.2.0 |
|
||||
| Breaking change / 不兼容变更 | 0.2.0 → 1.0.0 |
|
||||
| Change Type | Version Change |
|
||||
|-------------|----------------|
|
||||
| Bug fix | 0.1.0 → 0.1.1 |
|
||||
| New feature | 0.1.1 → 0.2.0 |
|
||||
| Breaking change | 0.2.0 → 1.0.0 |
|
||||
|
||||
---
|
||||
|
||||
## GitHub Actions Workflows / GitHub Actions 工作流
|
||||
## GitHub Actions Workflows
|
||||
|
||||
### release.yml
|
||||
|
||||
**Trigger / 触发条件:**
|
||||
- Manual workflow dispatch / 手动触发
|
||||
- Push of version tags (`v*`) / 推送版本标签
|
||||
**Triggers:**
|
||||
- ⭐ Push to `main` branch with `plugins/**/*.py` changes (auto-release)
|
||||
- Manual workflow dispatch
|
||||
- Push of version tags (`v*`)
|
||||
|
||||
**Actions / 动作:**
|
||||
1. Extracts all plugin versions / 提取所有插件版本
|
||||
2. Generates release notes / 生成发布说明
|
||||
3. Creates GitHub Release / 创建 GitHub Release
|
||||
**Actions:**
|
||||
1. Detects version changes compared to last release
|
||||
2. Collects updated plugin files
|
||||
3. Generates release notes (with commit history)
|
||||
4. Creates GitHub Release (with downloadable attachments)
|
||||
|
||||
### plugin-version-check.yml
|
||||
|
||||
**Trigger / 触发条件:**
|
||||
- Pull requests that modify `plugins/**/*.py` / 修改 `plugins/**/*.py` 的 PR
|
||||
**Trigger:**
|
||||
- Pull requests that modify `plugins/**/*.py`
|
||||
|
||||
**Actions / 动作:**
|
||||
1. Compares plugin versions between base and PR / 比较基础分支和 PR 的插件版本
|
||||
2. Comments on PR with version changes / 在 PR 上评论版本变化
|
||||
**Actions:**
|
||||
1. Compares plugin versions between base and PR
|
||||
2. Checks if version was updated
|
||||
3. Checks if PR description is detailed enough
|
||||
4. ❌ Fails if no version update detected
|
||||
5. ⚠️ Fails if PR description is too short
|
||||
|
||||
---
|
||||
|
||||
## Scripts / 脚本
|
||||
## Scripts
|
||||
|
||||
### extract_plugin_versions.py
|
||||
|
||||
Usage / 用法:
|
||||
Usage:
|
||||
|
||||
```bash
|
||||
# Output to console / 输出到控制台
|
||||
# Output to console
|
||||
python scripts/extract_plugin_versions.py
|
||||
|
||||
# Output as JSON / 输出为 JSON
|
||||
# Output as JSON
|
||||
python scripts/extract_plugin_versions.py --json
|
||||
|
||||
# Output as Markdown table / 输出为 Markdown 表格
|
||||
# Output as Markdown table
|
||||
python scripts/extract_plugin_versions.py --markdown
|
||||
|
||||
# Compare with previous version / 与之前版本比较
|
||||
# Compare with previous version
|
||||
python scripts/extract_plugin_versions.py --compare old_versions.json
|
||||
|
||||
# Save to file / 保存到文件
|
||||
# Save to file
|
||||
python scripts/extract_plugin_versions.py --json --output versions.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices / 最佳实践
|
||||
|
||||
1. **Always update version numbers** when making functional changes to plugins
|
||||
- 对插件进行功能性更改时**始终更新版本号**
|
||||
|
||||
2. **Write clear changelog entries** describing what changed and why
|
||||
- 编写清晰的更新日志条目，描述更改内容和原因
|
||||
|
||||
3. **Test locally** before creating a release
|
||||
- 在创建发布之前**本地测试**
|
||||
## Best Practices
|
||||
|
||||
1. **Always update version numbers** when making functional changes (required)
|
||||
2. **Write clear PR descriptions** describing what changed and why (required)
|
||||
3. **Test locally** before creating a PR
|
||||
4. **Use pre-releases** for testing new features
|
||||
- 使用**预发布**测试新功能
|
||||
|
||||
5. **Reference issues** in changelog entries when applicable
|
||||
- 在适用时在更新日志条目中**引用 issue**
|
||||
5. **Reference issues** in PR descriptions
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -14,51 +14,88 @@
|
||||
|
||||
---
|
||||
|
||||
## 自动发布流程 ⭐
|
||||
|
||||
当插件更新的 PR 合并到 `main` 分支时，会**自动触发**发布流程：
|
||||
|
||||
### PR 合并要求
|
||||
|
||||
修改插件文件的 PR 必须满足以下条件才能合并：
|
||||
|
||||
1. ✅ **版本号必须更新** - 插件的 `version` 字段必须有变化
|
||||
2. ✅ **PR 描述必须包含更新说明** - 至少 20 个字符的描述
|
||||
|
||||
如果不满足这些条件，PR 检查会失败，无法合并。
|
||||
|
||||
### 自动发布内容
|
||||
|
||||
合并成功后，系统会自动：
|
||||
|
||||
1. 🔍 检测版本变化（与上次 release 对比）
|
||||
2. 📝 生成发布说明（包含更新内容和提交记录）
|
||||
3. 📦 创建 GitHub Release（包含可下载的插件文件）
|
||||
4. 🏷️ 自动生成版本号（格式：`vYYYY.MM.DD-运行号`）
|
||||
|
||||
### Release 包含内容
|
||||
|
||||
- **plugins_release.zip** - 本次更新的所有插件文件打包
|
||||
- **plugin_versions.json** - 所有插件版本信息 (JSON 格式)
|
||||
- **发布说明** - 包含：
|
||||
- 新增/更新的插件列表
|
||||
- 相关提交记录
|
||||
- 所有插件版本表
|
||||
- 安装说明
|
||||
|
||||
---
|
||||
|
||||
## 发布流程
|
||||
|
||||
### 第 1 步：更新插件版本
|
||||
|
||||
当您对插件进行更改时，更新插件文档字符串中的版本号：
|
||||
当您对插件进行更改时，**必须**更新插件文档字符串中的版本号：
|
||||
|
||||
```python
|
||||
"""
|
||||
title: 我的插件
|
||||
author: Fu-Jie
|
||||
version: 0.2.0 # <- 更新这里
|
||||
version: 0.2.0 # <- 必须更新这里！
|
||||
...
|
||||
"""
|
||||
```
|
||||
|
||||
### 第 2 步：更新更新日志
|
||||
### 第 2 步：创建 PR 并添加更新说明
|
||||
|
||||
在 `CHANGELOG.md` 的 `[Unreleased]` 部分添加您的更改：
|
||||
在 PR 描述中说明更新内容（至少 20 个字符）：
|
||||
|
||||
```markdown
|
||||
## [Unreleased] / 未发布
|
||||
## 更新内容
|
||||
|
||||
### Added / 新增
|
||||
- 智能思维导图新功能
|
||||
|
||||
### Changed / 变更
|
||||
- 性能优化
|
||||
|
||||
### Fixed / 修复
|
||||
- 修复导出 bug
|
||||
- 新增 XXX 功能
|
||||
- 修复 YYY 问题
|
||||
- 优化 ZZZ 性能
|
||||
```
|
||||
|
||||
### 第 3 步：创建发布
|
||||
### 第 3 步：合并 PR
|
||||
|
||||
#### 方式 A：手动发布（推荐）
|
||||
满足检查条件后，合并 PR 到 `main` 分支，系统会自动创建 Release。
|
||||
|
||||
---
|
||||
|
||||
## 手动发布（可选）
|
||||
|
||||
除了自动发布，您也可以手动触发发布：
|
||||
|
||||
### 方式 A：手动触发
|
||||
|
||||
1. 前往 GitHub Actions → "Plugin Release / 插件发布"
|
||||
2. 点击 "Run workflow"
|
||||
3. 填写详细信息：
|
||||
- **version**: 例如 `v1.0.0`
|
||||
- **version**: 例如 `v1.0.0`（留空则自动生成）
|
||||
- **release_title**: 例如 "智能思维导图重大更新"
|
||||
- **release_notes**: Markdown 格式的附加说明
|
||||
- **prerelease**: 如果是预发布版本则勾选
|
||||
|
||||
#### 方式 B：基于标签的发布
|
||||
### 方式 B：基于标签的发布
|
||||
|
||||
```bash
|
||||
# 创建并推送版本标签
|
||||
@@ -66,25 +103,6 @@ git tag -a v1.0.0 -m "Release v1.0.0"
|
||||
git push origin v1.0.0
|
||||
```
|
||||
|
||||
这将自动触发发布工作流。
|
||||
|
||||
### 第 4 步：完成更新日志
|
||||
|
||||
发布后，将 `[Unreleased]` 的内容移动到新的版本部分：
|
||||
|
||||
```markdown
|
||||
## [Unreleased] / 未发布
|
||||
<!-- 暂时为空 -->
|
||||
|
||||
## [1.0.0] - 2024-01-15
|
||||
|
||||
### Added / 新增
|
||||
- 智能思维导图新功能
|
||||
|
||||
### Plugin Updates / 插件更新
|
||||
- `Smart Mind Map / 思维导图`: v0.7.0 → v0.8.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 版本编号
|
||||
@@ -110,13 +128,15 @@ git push origin v1.0.0
|
||||
### release.yml
|
||||
|
||||
**触发条件:**
|
||||
- ⭐ 推送到 `main` 分支且修改了 `plugins/**/*.py`（自动发布）
|
||||
- 手动触发 (workflow_dispatch)
|
||||
- 推送版本标签 (`v*`)
|
||||
|
||||
**动作:**
|
||||
1. 提取所有插件版本
|
||||
2. 生成发布说明
|
||||
3. 创建 GitHub Release
|
||||
1. 检测与上次 Release 的版本变化
|
||||
2. 收集更新的插件文件
|
||||
3. 生成发布说明（含提交记录）
|
||||
4. 创建 GitHub Release（含可下载附件）
|
||||
|
||||
### plugin-version-check.yml
|
||||
|
||||
@@ -125,7 +145,10 @@ git push origin v1.0.0
|
||||
|
||||
**动作:**
|
||||
1. 比较基础分支和 PR 的插件版本
|
||||
2. 在 PR 上评论版本变化
|
||||
2. 检查是否有版本更新
|
||||
3. 检查 PR 描述是否足够详细
|
||||
4. ❌ 如果没有版本更新，检查失败
|
||||
5. ⚠️ 如果 PR 描述过短，检查失败
|
||||
|
||||
---
|
||||
|
||||
@@ -154,11 +177,11 @@ python scripts/extract_plugin_versions.py --json --output versions.json
|
||||
|
||||
## 最佳实践
|
||||
|
||||
1. **始终更新版本号** - 对插件进行功能性更改时
|
||||
2. **编写清晰的更新日志** - 描述更改内容和原因
|
||||
3. **本地测试** - 在创建发布之前
|
||||
1. **始终更新版本号** - 对插件进行功能性更改时（必需）
|
||||
2. **编写清晰的 PR 描述** - 描述更改内容和原因（必需）
|
||||
3. **本地测试** - 在创建 PR 之前
|
||||
4. **使用预发布** - 测试新功能
|
||||
5. **引用 issue** - 在适用时在更新日志条目中
|
||||
5. **引用 issue** - 在 PR 描述中
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user