IT项目版本号使用规范参考

项目版本号使用规范指南

项目版本号使用规范指南

修订记录

版本	日期	修订内容	修订人
v1.0	2026-04-03	初始版本，采用季度版本号规则	张航
v2.0	2026-04-03	优化文档结构，添加快速参考和流程图	陈海波
v3.0	2026-04-03	将季度改为月份，添加修订记录章节	陈海波

快速参考

版本号格式

年份.月.发版次数
示例: 2026.04.1 = 2026年4月第1次发版

月份说明

月份值: 01-12（两位数字）
发版次数: 本月内第几次发版（从1开始）

快速命令

# 查看本月最新版本
ls release/RELEASE-2026.04.*.md | sort | tail -1

# 查看当前年份和月份
year=$(date +%Y); month=$(date +%m)
echo "当前: ${year}年${month}月"

# 获取最新版本号
ls release/RELEASE-*.md | sort | tail -1 | sed 's/.*RELEASE-\(.*\)\.md/\1/'

一、版本号规则

1.1 格式定义

版本号: 年份.月.发版次数

组成:

年份: 4位数字（如 2026）
月: 01-12（两位数字）
发版次数: 本月内第几次发版（从1开始）

1.2 版本号示例

版本号	含义	说明
`2026.04.1`	2026年4月第1次发版	本月首次
`2026.04.2`	2026年4月第2次发版	同月递增
`2026.05.1`	2026年5月第1次发版	新月首次
`2026.12.3`	2026年12月第3次发版	本月第3次

二、核心原则

2.1 独立性原则

每个项目独立管理版本号，互不影响。

项目A: 2026.04.1 → 2026.04.2 → 2026.04.3
项目B: 2026.04.1 → 2026.04.2 → 2026.05.1
项目C: 2026.04.5 → 2026.04.6

2.2 递增原则

基于本月历史版本递增。

检查本月最新版本 → 手动递增发版次数
无历史版本 → 从 .1 开始
有历史版本 → 递增（如 2026.04.1 → 2026.04.2）

2.3 时间导向原则

版本号包含时间信息，便于追溯。

优势：

📅 一眼看出发版时间
🔍 快速定位特定时间段版本
📊 便于版本历史分析
🎯 符合语义化版本理念

三、版本号生成流程

3.1 决策流程图

开始发版
    ↓
检查当前年份和月份
    ↓
检查 release/ 目录本月版本
    ↓
    ├─ 无版本 → 新版本: 年份.月.1
    │
    └─ 有版本 → 获取最新版本号
              ↓
              递增发版次数 → 新版本: 年份.月.(n+1)

3.2 实施步骤

Step 1: 确认当前时间

year=$(date +%Y)
month=$(date +%m)
echo "当前: ${year}年${month}月"

Step 2: 检查历史版本

ls release/RELEASE-${year}.${month}.*.md | sort | tail -1

Step 3: 确定新版本号

输出: release/RELEASE-2026.04.1.md → 新版本: 2026.04.2
无输出 → 新版本: 2026.04.1（本月首次）

四、发版流程（标准6步）

流程图

┌─────────────────┐
│ 1. 生成版本号    │
└────────┬────────┘
         ↓
┌─────────────────┐
│ 2. 创建RELEASE   │
│   文件           │
└────────┬────────┘
         ↓
┌─────────────────┐
│ 3. 创建Git       │
│   Release        │
└────────┬────────┘
         ↓
┌─────────────────┐
│ 4. 提交到Git     │
└────────┬────────┘
         ↓
┌─────────────────┐
│ 5. 验证Release   │
└────────┬────────┘
         ↓
┌─────────────────┐
│ 6. 记录到记忆    │
│   系统           │
└─────────────────┘

详细步骤

Step 1: 生成版本号

ls release/RELEASE-2026.04.*.md | sort | tail -1
# 手动确定: 2026.04.2

Step 2: 创建RELEASE文件

vim release/RELEASE-2026.04.2.md

文件模板:

# Release v2026.04.2

**发布日期**: 2026-04-03
**版本号**: 2026.04.2
**提交哈希**: abc1234

## 主要更新
- 功能 A
- 功能 B

## 详细变更
| 提交哈希 | 类型 | 说明 |
|---------|------|------|
| abc1234 | feat | 新增功能A |

Step 3: 创建Git Release

方式一：使用CLI工具（推荐）

Gitea:

tea releases create \
  --tag v2026.04.2 \
  --target master \
  --title "v2026.04.2" \
  --note-file release/RELEASE-2026.04.2.md

GitHub:

gh release create v2026.04.2 \
  --target master \
  --title "v2026.04.2" \
  --note-file release/RELEASE-2026.04.2.md

方式二：Web界面手动创建

Gitea Web界面操作步骤:

访问仓库页面
点击左侧菜单 "版本发布" 或右侧 "Releases"
点击 "新建版本发布" 按钮
填写信息：
- 标签: v2026.04.2
- 标题: v2026.04.2
- 目标: 选择分支（如 master）
- 说明: 复制RELEASE文件内容或直接输入
点击 "发布版本" 按钮

GitHub Web界面操作步骤:

访问仓库页面
点击右侧 "Releases"
点击 "Draft a new release"
填写信息：
- Tag: v2026.04.2
- Title: v2026.04.2
- Target: 选择分支
- Description: 复制RELEASE文件内容
点击 "Publish release"

Step 4: 提交到Git

git add release/RELEASE-2026.04.2.md
git commit -m "docs: 添加 v2026.04.2 发版记录"
git push origin master  # 需用户确认

Step 5: 验证Release

CLI验证:

tea releases list   # Gitea
gh release list     # GitHub

Web界面验证:

访问仓库的 Releases 页面
确认新版本已成功发布
检查版本信息、标签、说明是否正确

Step 6: 记录到记忆系统

supermemory --mode add \
  --type project-config \
  --scope user \
  --content "项目发版记录: v2026.04.2"

五、文件组织规范

5.1 目录结构

project-root/
├── release/                      # 发版记录（必须）
│   ├── RELEASE-2026.04.1.md
│   ├── RELEASE-2026.04.2.md
│   ├── RELEASE-2026.05.1.md
│   └── ...
├── docs/                         # 文档（可选）
│   ├── VERSION-GUIDE.md
│   └── ...
├── AGENTS.md                     # 开发规范（必须）
└── README.md                     # 项目说明（必须）

5.2 命名规范

RELEASE文件:

✅ RELEASE-2026.04.1.md
❌ release-2026.04.1.md
❌ RELEASE_v2026.04.1.md

版本号Tag:

✅ v2026.04.1
❌ 2026.04.1
❌ V2026.04.1

六、最佳实践

6.1 发版时机

✅ 建议发版:

重要功能更新完成
重要Bug修复完成
里程碑节点达成
需要对外发布

❌ 不建议发版:

小改动频繁发版
未完成的功能
测试未通过

6.2 版本历史维护

✅ 每个版本有完整RELEASE记录
✅ 包含详细变更列表
✅ 版本历史清晰可追溯
✅ 大版本变更添加迁移指南

6.3 团队协作

✅ 发版前通知团队成员
✅ 确认无未完成的PR/分支
✅ 发版后通知测试/运维
✅ 记录发版决策

七、常见问题FAQ

Q1: 如何确定新版本号？

答: 检查本月最新版本，手动递增。

ls release/RELEASE-2026.04.*.md | sort | tail -1

Q2: 不同项目可以有相同版本号吗？

答: ✅ 可以。版本号项目独立。

Q3: 发版后发现Bug怎么办？

答:

修复后发版新版本（2026.04.3）
不修改已发布版本号
新版本RELEASE中说明修复内容

Q4: 可以跳过版本号吗？

答: ❌ 不建议。版本号应连续递增。

Q5: 需要维护发版脚本吗？

答: ❌ 不需要。手动检查即可。

Q6: RELEASE文件必须放release/目录吗？

答: ✅ 必须。强制要求。

Q7: 月份必须两位数字吗？

答: ✅ 必须。如04、05、12，保持格式统一。

八、适用场景

8.1 适用项目

✅ 企业内部项目
✅ 长期维护项目
✅ 多人协作项目
✅ 需追溯发版历史

8.2 不适用场景

❌ 开源项目（建议用语义化版本1.0.0）
❌ 短期临时项目
❌ 个人练习项目
❌ 无需版本管理项目

九、迁移指南

9.1 从其他规则迁移

步骤:

评估必要性 - 是否需统一规则
制定计划 - 确定时间点、通知团队、备份历史
执行迁移 - 创建release/目录、整理历史、发布公告

9.2 新项目采用

步骤:

创建 release/ 目录
添加规范文档到 docs/VERSION-GUIDE.md
在 AGENTS.md 说明版本号规则
首次发版使用 年份.月.1

十、核心要点总结

要点	说明
格式	年份.月.发版次数
独立性	项目独立管理
递增	本月历史递增
文件位置	release/ 目录
无脚本	手动检查
时间导向	包含时间信息

优势:

📅 时间导向 - 版本号含时间信息
🔍 易于追溯 - 快速定位版本
🎯 简单明了 - 无需复杂计算
🚀 无需脚本 - 无额外维护
📊 独立管理 - 项目间不影响
✅ 统一规范 - 团队统一理解

附录：命令速查表

# 本月最新版本
ls release/RELEASE-2026.04.*.md | sort | tail -1

# 所有历史版本
ls release/RELEASE-*.md | sort

# 最新版本号
ls release/RELEASE-*.md | sort | tail -1 | sed 's/.*RELEASE-\(.*\)\.md/\1/'

# 当前年份和月份
year=$(date +%Y); month=$(date +%m)
echo "当前: ${year}年${month}月"

# 特定年份版本
ls release/RELEASE-2026.*.md | sort

# 特定月份版本
ls release/RELEASE-2026.04.*.md | sort

# 创建新RELEASE文件
vim release/RELEASE-2026.04.2.md

# Git提交RELEASE
git add release/RELEASE-2026.04.2.md
git commit -m "docs: 添加 v2026.04.2 发版记录"

# 创建Git Release (Gitea CLI)
tea releases create --tag v2026.04.2 --target master --title "v2026.04.2" --note-file release/RELEASE-2026.04.2.md

# 创建Git Release (GitHub CLI)
gh release create v2026.04.2 --target master --title "v2026.04.2" --note-file release/RELEASE-2026.04.2.md

# 验证Release (Gitea CLI)
tea releases list

# 验证Release (GitHub CLI)
gh release list

posted @ 2026-04-03 15:30 司野良阅读(17) 评论(0) 收藏举报

刷新页面返回顶部

司野良

业余程序员，如有错误请多多指教