项目规范指南

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

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）：

MIT License

Copyright (c) 2025 Your Name

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
...

3. README.md

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

规范

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

  • 内容包括：

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

    2. 安装方法

    3. 使用方法

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

    5. License 声明

示例

README.md：

# My Project

一个示例项目，用于展示版本管理规范。

## 📦 安装
```bash
composer install

4. CHANGELOG

作用：系统记录变更

示例：

# Changelog
所有对本项目的重要变更都会记录在这里。

## [Unreleased]

## [1.1.0] - 2025-09-20
### Added
- 新增用户评论功能 (#123)

### Fixed
- 修复文件上传失败的问题 (#456)

### Changed
- 优化查询性能 (#789)

## [1.0.0] - 2025-08-01
### Added
- 初始版本发布

5. Releases

规范

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

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

  • 内容包括：

    • 版本号

    • 发布日期

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

    • Breaking Changes 必须单独列出

示例

Release Notes 示例：

## 🚀 Features
- 新增用户评论功能 (#123)

## 🐛 Bug Fixes
- 修复文件上传失败的问题 (#456)

## ⚠️ Breaking Changes
- 移除旧的 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。

示例

命令：

# 打 tag
git tag v1.1.0

# 推送 tag
git push origin v1.1.0

7. 项目目录结构示例

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

8. 推荐工作流

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