Skip to content

Commit 934fcbf

Browse files
code-galcode-gal
committed
chore: improve release workflow with bilingual notes and enhanced automation
- Add bilingual Release Notes (Chinese from CHANGELOG.md, English from git commits) - Fix release scripts to use 'github' remote instead of 'origin' - Remove VERSION file, unify version management in git tags and .csproj - Restore full version properties in .csproj (AssemblyVersion, FileVersion, InformationalVersion) - Refactor release guide documentation with detailed automation steps - Update release.yml to extract Chinese content from CHANGELOG.md
1 parent 7c35157 commit 934fcbf

6 files changed

Lines changed: 166 additions & 62 deletions

File tree

‎.github/workflows/release.yml‎

Lines changed: 29 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -29,25 +29,47 @@ jobs:
2929
- name: Generate Release Notes
3030
id: release_notes
3131
run: |
32+
VERSION=${{ steps.get_version.outputs.VERSION }}
33+
34+
# 从 CHANGELOG.md 提取中文版本说明
35+
if [ -f "CHANGELOG.md" ]; then
36+
# 提取当前版本的中文内容
37+
CHANGELOG_CN=$(sed -n "/## \[$VERSION\]/,/## \[/p" CHANGELOG.md | sed '$d' | tail -n +2)
38+
else
39+
CHANGELOG_CN=""
40+
fi
41+
3242
# 获取上一个标签
3343
PREV_TAG=$(git describe --abbrev=0 --tags $(git rev-list --tags --skip=1 --max-count=1) 2>/dev/null || echo "")
3444
35-
# 生成变更日志
45+
# 生成英文变更日志（从 git commit）
3646
if [ -z "$PREV_TAG" ]; then
37-
CHANGELOG=$(git log --pretty=format:"- %s (%h)" --no-merges)
47+
CHANGELOG_EN=$(git log --pretty=format:"- %s (%h)" --no-merges)
48+
else
49+
CHANGELOG_EN=$(git log ${PREV_TAG}..HEAD --pretty=format:"- %s (%h)" --no-merges)
50+
fi
51+
52+
# 生成 Release Notes（中文优先，英文在后）
53+
if [ -n "$CHANGELOG_CN" ]; then
54+
echo "## 📝 更新说明 / Release Notes" > release_notes.md
55+
echo "" >> release_notes.md
56+
echo "$CHANGELOG_CN" >> release_notes.md
57+
echo "" >> release_notes.md
58+
echo "---" >> release_notes.md
59+
echo "" >> release_notes.md
3860
else
39-
CHANGELOG=$(git log ${PREV_TAG}..HEAD --pretty=format:"- %s (%h)" --no-merges)
61+
echo "## 📝 Release Notes" > release_notes.md
62+
echo "" >> release_notes.md
4063
fi
4164
42-
# 将变更日志保存到文件
43-
echo "## 🚀 What's Changed" > release_notes.md
65+
echo "## 🚀 What's Changed (Auto-generated)" >> release_notes.md
4466
echo "" >> release_notes.md
45-
echo "$CHANGELOG" >> release_notes.md
67+
echo "$CHANGELOG_EN" >> release_notes.md
4668
echo "" >> release_notes.md
4769
echo "## 📦 Docker Image" >> release_notes.md
4870
echo "" >> release_notes.md
4971
echo '```bash' >> release_notes.md
50-
echo "docker pull ghcr.io/${{ github.repository }}:${{ steps.get_version.outputs.VERSION }}" >> release_notes.md
72+
echo "docker pull ghcr.io/${{ github.repository }}:$VERSION" >> release_notes.md
5173
echo "# 或使用 latest 标签" >> release_notes.md
5274
echo "docker pull ghcr.io/${{ github.repository }}:latest" >> release_notes.md
5375
echo '```' >> release_notes.md

‎CHANGELOG.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1010
### Planned
1111
- i18n
1212

13+
## [0.8.3] - 2026-01-05
14+
15+
### Changed
16+
- 🔧 改进发布工作流，GitHub Release 现在同时显示中文和英文说明
17+
- 🔧 修复发布脚本使用正确的 Git 远程仓库名称（`github` 而非 `origin`）
18+
- 🔧 移除 VERSION 文件，版本信息统一由 Git tags 和 .csproj 管理
19+
- 📝 重构发布指南文档，详细说明自动化脚本的 10 项功能
20+
- 🔧 恢复 .csproj 中的完整版本号配置（AssemblyVersion、FileVersion、InformationalVersion）
21+
22+
### Technical
23+
- Release Notes 现在从 CHANGELOG.md 提取中文内容，从 git commit 生成英文内容
24+
- 发布脚本自动化：检查状态、更新版本号、提交推送、创建标签
25+
- 双语 Release Notes 支持 Atom/RSS 订阅
26+
1327
## [0.8.2] - 2026-01-05
1428

1529
### Added

‎Docs-Tools/NamBlog发布指南.md‎

Lines changed: 114 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,123 @@
11
# NamBlog 发布指南
22

3-
## 发布步骤
3+
## 前置准备
4+
5+
### Git 远程仓库配置
6+
**重要**：发布脚本要求 GitHub 远程仓库名称必须是 `github`（不是默认的 `origin`）。
7+
8+
检查当前配置：
9+
```bash
10+
git remote -v
11+
```
12+
13+
如果远程仓库名是 `origin`，需要重命名：
14+
```bash
15+
git remote rename origin github
16+
```
17+
18+
或添加新的远程仓库：
19+
```bash
20+
git remote add github https://github.com/your-username/namblog.git
21+
```
22+
23+
### 工作流说明
424

5-
1. **代码推送到 GitHub**（至少默认分支 `main` ），确保仓库里已经存在：
6-
- `.github/workflows/release.yml`
7-
- `.github/workflows/ci.yml`
25+
本项目有两个 GitHub Actions 工作流：
826

9-
2. **推送Tag**。
10-
- 只 push 分支时，只会触发 `CI`（`ci.yml`）
11-
- 只有 push 形如 `vX.Y.Z` 的 tag（例如 `v0.8.0`）才会触发 `Release and Build`（`release.yml`）
27+
| 工作流 | 文件 | 触发条件 | 作用 |
28+
|--------|------|---------|------|
29+
| **CI** | `.github/workflows/ci.yml` | 推送代码到 `main`/`develop` 分支或创建 PR | ✅ 编译检查<br>✅ 构建测试 Docker 镜像<br>❌ 不发布 Release<br>❌ 不推送镜像到仓库 |
30+
| **Release and Build** | `.github/workflows/release.yml` | 推送形如 `v*.*.*` 的 tag（如 `v0.8.2`） | ✅ 自动生成 Release Notes<br>✅ 创建 GitHub Release<br>✅ 构建多架构 Docker 镜像<br>✅ 推送到 GHCR |
1231

13-
3. **确保 tag 指向的提交里包含 `release.yml`**。
14-
- GitHub Actions 运行时会使用“tag 指向的那次提交”里的 workflow 文件。
32+
**CI 工作流**：用于日常开发，确保代码质量，每次推送代码都会运行。
33+
**Release 工作流**：用于正式发布，只在推送版本标签时运行。
1534

16-
4. **仓库 Actions 权限设置**：
17-
- 进入 GitHub 仓库 → Settings → Actions → General → Workflow permissions
18-
- 建议选 **Read and write permissions**（否则即使 workflow 里写了 `contents: write` / `packages: write` 也可能受限）
35+
### 首次手动发布（仅首次需要）
1936

20-
5. **GHCR 镜像包可见性**：
21-
- 首次推送镜像成功后，Packages 里可能默认是 Private。
22-
- 如果你希望“用户无需登录即可拉取”，需要把该 Package 的 Visibility 改为 **Public**。
37+
如果是第一次设置发布流程，需要配置以下内容：
2338

39+
1. **确保仓库包含工作流文件**：
40+
- `.github/workflows/release.yml`
41+
- `.github/workflows/ci.yml`
42+
43+
2. **仓库 Actions 权限设置**：
44+
- 进入 GitHub 仓库 Settings Actions General Workflow permissions
45+
- 选择 **Read and write permissions**（允许创建 Release 和推送 Packages）
46+
47+
3. **GHCR 镜像包可见性设置**：
48+
- 首次推送镜像成功后，进入仓库 Packages
49+
- 找到 `namblog` 镜像包，点击 Package settings
50+
- 将 Visibility 改为 **Public**（允许用户无需登录拉取镜像）
51+
52+
4. **创建首个 Release**：
53+
```bash
54+
# 使用脚本（推荐）
55+
.\Docs-Tools\release.ps1 -Version "0.8.0" -Message "Initial release"
56+
57+
# 或手动
58+
git tag -a v0.8.0 -m "Release v0.8.0"
59+
git push github v0.8.0
60+
```
61+
62+
## 发布步骤
63+
64+
### 推荐方式：使用发布脚本（自动化）
65+
66+
**一键发布命令**：
2467
```bash
25-
# 使用脚本（推荐）
26-
.\release.ps1 -Version "0.8.0" -Message "Initial release" # Windows
27-
./release.sh 0.8.0 "Initial release" # Linux/Mac
68+
# Windows PowerShell
69+
.\Docs-Tools\release.ps1 -Version "0.8.3" -Message "Bug fixes and improvements"
2870

29-
# 或手动
30-
git tag -a v0.8.0 -m "Release v0.8.0"
31-
git push github v0.8.0
71+
# Linux/Mac Bash
72+
./Docs-Tools/release.sh 0.8.3 "Bug fixes and improvements"
3273
```
3374

34-
GitHub Actions 自动执行：创建 Release、构建 Docker 镜像（amd64/arm64）、推送到 GHCR。
35-
75+
**脚本自动化功能**（一条命令完成以下所有步骤）：
76+
1. 检查工作区状态（未提交更改会警告）
77+
2. 检查当前分支（非主分支会警告）
78+
3. 验证版本号格式（MAJOR.MINOR.PATCH）
79+
4. 检查 tag 是否已存在（避免重复发布）
80+
5. 自动更新 `NamBlog.API.csproj` 中的版本号
81+
6. 提示确认 `CHANGELOG.md` 已更新
82+
7. 提交版本更改到 Git
83+
8. 推送代码到 GitHub
84+
9. 创建并推送版本 tag（触发 Release 工作流）
85+
10. 显示 GitHub Actions 和 Release 链接
86+
87+
**发布前准备**：
88+
1. 在 `CHANGELOG.md` 中添加新版本的更新说明（中文）
89+
2. 确保所有代码已提交（脚本会检查）
90+
91+
**Release Notes 生成策略**：
92+
- **中文内容**：从 `CHANGELOG.md` 自动提取当前版本的更新说明（手动维护，更详细）
93+
- **英文内容**：从 git commit 消息自动生成（Auto-generated，面向开发者）
94+
- **双语支持**：方便不同语言用户通过 Atom/RSS 订阅查看更新
95+
96+
推送 tag 后，GitHub Actions 自动执行：创建双语 Release、构建多架构 Docker 镜像（amd64/arm64）、推送到 GHCR。
97+
98+
---
99+
100+
### 手动发布（不使用脚本）
101+
102+
如果不使用脚本，需要手动执行以下步骤：
103+
104+
1. **更新 CHANGELOG.md**（添加新版本说明）
105+
2. **更新 .csproj 版本号**（修改 `<Version>0.8.3</Version>`）
106+
3. **提交并推送更改**：
107+
```bash
108+
git add CHANGELOG.md NamBlog.API/NamBlog.API.csproj
109+
git commit -m "chore: bump version to 0.8.3"
110+
git push github main
111+
```
112+
4. **创建并推送 tag**：
113+
```bash
114+
git tag -a v0.8.3 -m "Release v0.8.3"
115+
git push github v0.8.3
116+
```
117+
118+
推送 tag 后，GitHub Actions 会自动触发发布流程。
119+
120+
---
36121
## 常见问题：为什么只看到 CI 成功，但没有 Release 和镜像？
37122

38123
这通常意味着只 push 了分支提交（触发 `CI`），但**没有 push tag**（不会触发 `release.yml`）。
@@ -61,29 +146,22 @@ GitHub Actions 自动执行：创建 Release、构建 Docker 镜像（amd64/arm6
61146
- `0.8` - 追踪 0.8.x 所有版本
62147
- `0.8.0` - 精确版本，永不变
63148

64-
## 使用建议
149+
## Docker 镜像使用建议
65150

66151
```yaml
67-
# 生产（推荐）
152+
# 生产环境（推荐）
68153
image: ghcr.io/code-gal/namblog:stable
69154

70-
# 生产（保守）
155+
# 生产环境（保守）
71156
image: ghcr.io/code-gal/namblog:0.8.0
72157

73-
# 测试
158+
# 测试环境
74159
image: ghcr.io/code-gal/namblog:1
75160

76-
# 开发
161+
# 开发环境
77162
image: ghcr.io/code-gal/namblog:latest
78163
```
79164
80-
## 语义化版本
81-
82-
**MAJOR.MINOR.PATCH**
83-
- MAJOR: 不兼容的 API 变更
84-
- MINOR: 新功能（兼容）
85-
- PATCH: Bug 修复
86-
87165
## 版本回滚
88166
89167
```bash
@@ -93,3 +171,4 @@ git push github :refs/tags/v0.8.1
93171

94172
# 在 GitHub 删除 Release
95173
```
174+

‎Docs-Tools/release.ps1‎

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -75,11 +75,6 @@ if ($tagExists) {
7575
exit 1
7676
}
7777

78-
# 更新 VERSION 文件
79-
Write-Host "更新 VERSION 文件..." -ForegroundColor Yellow
80-
Set-Content -Path "VERSION" -Value $Version
81-
git add VERSION
82-
8378
# 更新 .csproj 文件中的版本号
8479
Write-Host "更新 .csproj 版本号..." -ForegroundColor Yellow
8580
$csprojPath = "NamBlog.API\NamBlog.API.csproj"
@@ -111,7 +106,7 @@ if ($changelogUpdated -ne "y" -and $changelogUpdated -ne "Y") {
111106
Write-Host "提交版本更新..." -ForegroundColor Yellow
112107
try {
113108
git commit -m "chore: bump version to $Version"
114-
git push origin $currentBranch
109+
git push github $currentBranch
115110
} catch {
116111
Write-Host "⚠️ 提交可能已存在，继续..." -ForegroundColor Yellow
117112
}
@@ -122,7 +117,7 @@ git tag -a "v$Version" -m $Message
122117

123118
# 推送标签
124119
Write-Host "推送标签到远程仓库..." -ForegroundColor Yellow
125-
git push origin "v$Version"
120+
git push github "v$Version"
126121

127122
Write-Host ""
128123
Write-Host "✅ 发布成功!" -ForegroundColor Green

‎Docs-Tools/release.sh‎

Lines changed: 4 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -80,11 +80,6 @@ if git rev-parse "v${VERSION}" >/dev/null 2>&1; then
8080
exit 1
8181
fi
8282

83-
# 更新 VERSION 文件
84-
echo -e "${YELLOW}更新 VERSION 文件...${NC}"
85-
echo "${VERSION}" > VERSION
86-
git add VERSION
87-
8883
# 更新 .csproj 文件中的版本号
8984
echo -e "${YELLOW}更新 .csproj 版本号...${NC}"
9085
CSPROJ_PATH="NamBlog.API/NamBlog.API.csproj"
@@ -116,15 +111,15 @@ fi
116111
# 提交更改
117112
echo -e "${YELLOW}提交版本更新...${NC}"
118113
git commit -m "chore: bump version to ${VERSION}" || true
119-
git push origin $CURRENT_BRANCH
114+
git push github $CURRENT_BRANCH
120115

121116
# 创建标签
122117
echo -e "${YELLOW}创建标签 v${VERSION}...${NC}"
123118
git tag -a "v${VERSION}" -m "${MESSAGE}"
124119

125120
# 推送标签
126121
echo -e "${YELLOW}推送标签到远程仓库...${NC}"
127-
git push origin "v${VERSION}"
122+
git push github "v${VERSION}"
128123

129124
echo ""
130125
echo -e "${GREEN}✅ 发布成功!${NC}"
@@ -136,6 +131,6 @@ echo " 2. 构建 Docker 镜像"
136131
echo " 3. 推送到 GitHub Container Registry"
137132
echo ""
138133
echo "查看进度:"
139-
echo " Actions: https://github.com/$(git config --get remote.origin.url | sed 's/.*github.com[:/]\(.*\)\.git/\1/')/actions"
140-
echo " Releases: https://github.com/$(git config --get remote.origin.url | sed 's/.*github.com[:/]\(.*\)\.git/\1/')/releases"
134+
echo " Actions: https://github.com/$(git config --get remote.github.url | sed 's/.*github.com[:/]\(.*\)\.git/\1/')/actions"
135+
echo " Releases: https://github.com/$(git config --get remote.github.url | sed 's/.*github.com[:/]\(.*\)\.git/\1/')/releases"
141136
echo ""

‎NamBlog.API/NamBlog.API.csproj‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,9 @@
77

88
<!-- 版本信息 -->
99
<Version>0.8.2</Version>
10-
<!--<AssemblyVersion>0.8.2</AssemblyVersion> -->
11-
<!--<FileVersion>0.8.2</FileVersion> -->
12-
<!--<InformationalVersion>0.8.2</InformationalVersion> -->
10+
<AssemblyVersion>0.8.2</AssemblyVersion>
11+
<FileVersion>0.8.2</FileVersion>
12+
<InformationalVersion>0.8.2</InformationalVersion>
1313

1414
<!-- 产品信息 -->
1515
<Product>NamBlog</Product>
@@ -53,4 +53,3 @@
5353
</ItemGroup>
5454

5555
</Project>
56-

0 commit comments

Comments
 (0)