按 Enter 键跳转到正文

项目规范指南

发布于 2023年4月1日，作者 Leanku

项目规范指南

本规范适用于团队/开源项目的版本管理，目标是做到：规范化、可追踪、可溯源。

1. 版本管理 (Versioning)

  • 遵循 语义化版本规范 (Semantic Versioning, SemVer 2.0.0)
    MAJOR.MINOR.PATCH

    • MAJOR：主版本号，不兼容的 API 改动

    • MINOR：次版本号，新增功能（向下兼容）

    • PATCH：修订号，修复 bug（向下兼容）

  • 先行版本号及版本编译信息可以加到“主版本号.次版本号.修订号”的后面，作为延伸。
  • 预发布版本：1.0.0-alpha.1、2.0.0-rc.1

参考语义化版本规范：https://semver.org/lang/zh-CN/

2. LICENSE (MIT)

作用：MIT，明确版权

规范

  • 项目必须包含 LICENSE 文件，放置于项目根目录。

  • 推荐使用 MIT License（宽松、常用，几乎所有开源项目可接受）。

  • 文件名统一：LICENSE（不要写成 LICENSE.txt 或 license.md）。

  • 在 README.md 中需明确说明 License 类型。

示例

LICENSE 文件（MIT）：

1MIT License
2
3Copyright (c) 2025 Your Name
4
5Permission is hereby granted, free of charge, to any person obtaining a copy
6of this software and associated documentation files (the "Software"), to deal
7...

3. README.md

作用：项目介绍 + 使用 + License

规范

  • 项目必须包含 README.md 文件，作为项目首页说明文档。

  • 内容包括：

    1. 项目介绍（一句话简介）

    2. 安装方法

    3. 使用方法

    4. 版本规范说明（链接到 CHANGELOG.md）

    5. License 声明

示例

README.md：

1# My Project
2
3一个示例项目，用于展示版本管理规范。
4
5## 📦 安装
6```bash
7composer install

4. CHANGELOG

作用：系统记录变更

示例：

 1# Changelog
 2所有对本项目的重要变更都会记录在这里。
 3
 4## [Unreleased]
 5
 6## [1.1.0] - 2025-09-20
 7### Added
 8- 新增用户评论功能 (#123)
 9
10### Fixed
11- 修复文件上传失败的问题 (#456)
12
13### Changed
14- 优化查询性能 (#789)
15
16## [1.0.0] - 2025-08-01
17### Added
18- 初始版本发布

5. Releases

规范

  • 每次发版必须在 GitHub/GitLab Release 创建 Release。

  • Release 名称与 tag 保持一致（如 v1.1.0）。

  • 内容包括：

    • 版本号

    • 发布日期

    • 更新内容（从 CHANGELOG.md 中复制）

    • Breaking Changes 必须单独列出

示例

Release Notes 示例：

1## 🚀 Features
2- 新增用户评论功能 (#123)
3
4## 🐛 Bug Fixes
5- 修复文件上传失败的问题 (#456)
6
7## ⚠️ Breaking Changes
8- 移除旧的 API v1 接口，请迁移至 v2

6. Git Tag

规范

  • 使用 语义化版本号 (SemVer) 打标签。

  • 格式：vMAJOR.MINOR.PATCH

    • ✅ v1.0.0

    • ✅ v1.2.3

    • ✅ v2.0.0-beta.1

    • ❌ release-1.0

  • 每个 tag 必须对应一次 Release。

  • 禁止随意删除/修改已发布的 tag。

示例

命令：

1# 打 tag
2git tag v1.1.0
3
4# 推送 tag
5git push origin v1.1.0

7. 项目目录结构示例

1my-project/
2├── src/                     # 源代码
3├── tests/                   # 单元测试
4├── docs/                    # 项目文档
5├── .gitignore               # Git 忽略文件
6├── CHANGELOG.md             # 更新日志
7├── LICENSE                  # 开源协议 (MIT)
8├── README.md                # 项目说明
9└── package.json / composer.json / pyproject.toml (根据语言)

8. 推荐工作流

  1. 开发完成 → 更新 CHANGELOG.md
  2. 提交代码并打标签：
    1git commit -m "release: v1.1.0"
2git tag v1.1.0
3git push origin v1.1.0
  3. 在 GitHub/GitLab 上创建 Release，复制 CHANGELOG.md 对应内容
  4. 用户下载最新 Release，即可使用

发布在 ProjectManagement

发表评论