docs/Git-Management
6
0
Fork 0
Code Activity

更新 README.md

Browse Source
This commit is contained in:
许轲
2025-08-22 13:50:26 +08:00
parent b4cf9e2ddf
commit 67b48d58cf
1 changed files with 205 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files

274
README.md
View File

@@ -12,89 +12,143 @@
## 2. 分支管理 ## 2. 分支管理
本项目采用以下分支策略进行代码管理: 本项目采用以下分支策略进行代码管理，分为 **主线分支（长期存在）** 和 **辅助分支（短期存在）** 两个层级。
### 2.1 主分支 (`main`) ### 2.1 主线分支（长期存在）
* **用途**: `main` 分支始终保持项目的稳定版本，且此分支的代码随时可以部署到生产环境。 #### `main` 分支
* **更新规则**: 仅允许经过充分测试并审查的代码合并到 `main` 分支。每次从 `dev` 或 `release` 分支合并到 `main` 时，必须打上版本标签。
### 2.2 开发分支 (`dev`) * **用途**:
* **用途**: `dev` 分支是所有开发工作的集成分支。所有的新功能开发应首先合并至 `dev` 分支，并经过集成测试后再合并到 `main`。 * 始终保持项目的稳定版本；
* **更新规则**: 所有功能开发完成后，应合并至 `dev` 分支进行集成测试，确认没有问题后再合并到 `main`。 * 此分支的代码随时可以部署到生产环境。
### 2.3 功能分支 (`feature/*`) * **更新规则**:
* 严禁直接在 `main` 分支上开发；
* 仅允许经过充分测试并审查的代码合并；
* 每次从 `release` 分支合并到 `main` 时，必须打上版本标签。
#### `dev` 分支
* **用途**:
* 集成分支，是所有开发工作的汇集点；
* 所有新功能和修复分支都应合并至 `dev` 进行集成测试。
* **更新规则**:
* 功能开发完成后 → 合并至 `dev` ；
* `dev` 分支应保持可运行状态，避免不稳定代码长期停留。
### 2.2 辅助分支（短期存在，用完即删）
#### 功能分支 (`feature/*`)
* **用途**:
* 用于新功能开发，每个功能一个独立分支。
* **命名规范**:
* `feature/功能描述`，如: `feature/ast-folding`、`feature/user-cli`；
* 分支名称统一使用小写字母，单词间用破折号（`-`）分隔。
* **用途**: 每个新功能的开发都应从 `dev` 分支创建一个独立的功能分支。
* **命名规范**: `feature/功能描述`，例如: `feature/ast-folding`、`feature/user-cli`。所有分支名称应使用小写字母，并且使用破折号（`-`）分隔单词。
* **开发流程**: * **开发流程**:
1. 从 `dev` 分支拉取最新代码。 1. 从 `dev` 分支拉取最新代码并创建分支；
2. 完成功能开发后，在本地提交代码并推送至远程仓库。 2. 完成功能开发后，本地提交并推送到远程仓库；
3. 创建拉取请求（PR），并合并到 `dev` 分支。 3. 创建拉取请求（PR），合并回 `dev` 分支。
### 2.4 修复分支 (`bugfix/*`) #### 修复分支 (`bugfix/*`)
* **用途**:
* 用于修复一般性 Bug；
* 可从 `dev` 或 `main` 创建，视问题是否影响生产环境而定。
* **命名规范**:
* `bugfix/bug描述`，如: `bugfix/fix-ast-error`。
* 分支名称统一使用小写字母，单词间用破折号（`-`）分隔。
* **用途**: 用于修复 Bug，修复分支可以从 `dev` 或 `main` 分支创建。
* **命名规范**: `bugfix/bug描述`，例如: `bugfix/fix-ast-error`。
* **开发流程**: * **开发流程**:
1. 从 `dev` 或 `main` 分支拉取最新代码。 1. 从 `dev` 或 `main` 分支拉取最新代码；
2. 完成修复后，提交修改并推送至远程仓库。 2. 完成修复后提交并推送到远程仓库；
3. 创建拉取请求（PR），并合并到相应分支。 3. 创建拉取请求（PR），合并回相应分支（通常为 `dev`，若需立即上线可合并至 `main`）。
### 2.5 发布分支 (`release/*`) #### 发布分支 (`release/*`)
* **用途**:
* 用于版本发布的准备（文档更新、版本号调整等）；
* 保证发布过程稳定，不受未完成功能的影响。
* **命名规范**:
* `release/vX.X.X`，如: `release/v1.0.0`。
* **用途**: 当 `dev` 分支的功能开发完成且准备发布时，应创建一个 `release` 分支进行发布准备。
* **命名规范**: `release/vX.X.X`，例如: `release/v1.0.0`。
* **开发流程**: * **开发流程**:
1. 从 `dev` 分支创建 `release` 分支。 1. 从 `dev` 分支创建 `release` 分支；
2. 在 `release` 分支上进行版本发布的最终准备工作，如文档更新、版本号调整等。 2. 在 `release` 分支完成发布前准备工作（文档、版本号、配置修改等）；
3. 完成发布准备后，将 `release` 分支合并至 `main` 并打上版本标签，随后将变更合并回 `dev` 分支。 3. 准备完成后，将 `release` 分支合并至 `main` 并打上版本标签；
4. 将 `release` 分支变更同步合并回 `dev`，保证开发分支与主分支一致。
### 2.6 热修复分支 (`hotfix/*`) #### 热修复分支 (`hotfix/*`)
* **用途**:
* 用于生产环境中的紧急问题修复（如严重 Bug、系统崩溃等）；
* 保证在最短时间内修复并恢复服务。
* **命名规范**:
* `hotfix/bug描述`，如: `hotfix/fix-production-crash`。
* **用途**: 当生产环境中发现紧急问题（如 Bug 或系统崩溃等），需在 `main` 分支上进行快速修复时，应创建一个 `hotfix` 分支进行修复。
* **命名规范**: `hotfix/bug描述`，例如: `hotfix/fix-production-crash`。
* **开发流程**: * **开发流程**:
1. 从 `main` 分支创建 `hotfix` 分支，确保该分支包含生产环境中最新的稳定版本。 1. 从 `main` 分支创建 `hotfix` 分支，保证包含生产环境的最新稳定版本；
2. 在 `hotfix` 分支上进行问题修复和相关调整。 2. 在 `hotfix` 分支完成修复并提交推送；
3. 完成修复后，提交修改并推送至远程仓库。 3. 创建拉取请求（PR），将 `hotfix` 分支合并至 `main` 并打上版本标签；
4. 创建拉取请求（PR），将 `hotfix` 分支合并至 `main` 分支并打上版本标签，确保生产环境修复生效。 4. 同时将修复内容合并回 `dev`，避免后续开发再次出现同样问题；
5. 将修复后的变更合并回 `dev` 分支，确保所有的修复和调整同步到开发分支，防止后续开发中出现同样的问题。 5. **回滚策略**：若修复未能解决问题，立即回滚合并，删除 `hotfix` 分支并通知团队，确保不影响生产环境。
6. **回滚策略**: 如果热修复未能解决问题，立即回滚合并，删除 `hotfix` 分支并通知团队，确保不影响生产环境。 ---
### 2.7 分支流程图 ### 2.7 分支流程图
```mermaid ```mermaid
flowchart LR flowchart LR
%% ---------- Core dev cycle ---------- %% ---------- Core dev cycle ----------
subgraph CORE[Core Flow] subgraph CORE[ ]
direction LR direction LR
F[Feature] --> D[Dev] --> R[Release] --> M[Main] --> P[Production]
R --> D
end
%% ---------- Fix streams grouped ----------
subgraph FIX[Fix Streams]
direction TB
B[Bugfix] B[Bugfix]
H[Hotfix] H[Hotfix]
F[Feature]
D[Dev]
R[Release]
M[Main]
P[Production]
F --> D
D -. create .-> R
R --> M
R --> D
D -. create .-> F
M --Tag--> P
M --- D
end end
%% Bugfix: can start from Dev or Main, merges back to both %% Bugfix: can start from Dev or Main, merges back to both
D -. create .-> B D -. create .-> B
M -. create .-> B
B --> D B --> D
B --> M
%% Hotfix: from Main, then merge back to Main & Dev %% Hotfix: from Main, then merge back to Main
M -. create .-> H M -. create .-> H
H --> M H --> M
H --> D
%% ---------- Styling ---------- %% ---------- Styling ----------
classDef core fill:#EEF5FF,stroke:#5B8DEF,stroke-width:2px,rx:10,ry:10; classDef core fill:#EEF5FF,stroke:#5B8DEF,stroke-width:2px,rx:10,ry:10;
@@ -117,7 +171,6 @@ flowchart LR
* **所有分支** 通过 **PR（拉取请求）** 合并，需经过代码审查。 * **所有分支** 通过 **PR（拉取请求）** 合并，需经过代码审查。
## 3. 提交规范 ## 3. 提交规范
为确保提交信息清晰且易于理解，遵循以下提交规范: 为确保提交信息清晰且易于理解，遵循以下提交规范:
@@ -153,7 +206,8 @@ flowchart LR
### 3.2 提交实践 ### 3.2 提交实践
* 提交时，请确保代码已完成并通过所有相关测试。 * 提交时，请确保代码是否符合项目的编码规范。
* 每次提交应仅包含少量且相关的变更，避免一次性提交过多内容，以便于追踪和管理。 * 每次提交应仅包含少量且相关的变更，避免一次性提交过多内容，以便于追踪和管理。
--- ---
@@ -163,20 +217,13 @@ flowchart LR
### 4.1 拉取请求流程 ### 4.1 拉取请求流程
1. 开发者在完成功能或修复后，创建 PR，将其分支合并至 `dev` 或 `main` 分支。 1. 开发者在完成功能或修复后，创建 PR，将其分支合并至 `dev` 或 `main` 分支。
2. 其他团队成员进行代码审查，重点检查代码质量、功能完整性及测试覆盖率。 2. 其他团队成员进行代码审查，重点检查代码质量、功能完整性。
3. 审查通过后，PR 将被合并,PR 合并后删除 feature/bugfix 分支，避免仓库臃肿。 3. 审查通过后，PR 将被合并,PR 合并后删除 `feature/bugfix` 分支，避免仓库臃肿。
### 4.2 代码审查 ### 4.2 代码审查
* 所有 PR 必须经过至少一名开发者的代码审查。 * 所有 PR 必须经过至少一名开发者的代码审查。
* 审查时应关注以下方面(可简化步骤): * 审查时应关注功能是否按预期工作。
* 代码是否符合项目的编码规范。(可选)
* 是否提供了足够的单元测试覆盖。(可选)
* 是否存在冗余代码或复杂度过高的部分。(可选)
* 功能是否按预期工作。(必须)
* 审查者应在 PR 中提供反馈，确保代码质量高，符合团队要求。(可选)
--- ---
@@ -204,6 +251,10 @@ flowchart LR
* **注意事项**: * **注意事项**:
* 所有版本标签必须基于 `main` 分支最新的稳定提交。 * 所有版本标签必须基于 `main` 分支最新的稳定提交。
* 历史项目使用 Gitea 托管以 `v1.0.0` 为初始版本。
* 新项目使用 Gitea 托管以 `v0.1.0` 为初始版本。
### 5.2 发布流程 ### 5.2 发布流程
@@ -238,20 +289,74 @@ flowchart LR
### 6.2 Issue 分类 ### 6.2 Issue 分类
| 标签名 | 说明 | 用途举例 | <table style="border-collapse:separate;border-spacing:0;width:100%;font-size:15px;">
| --------------- | ---------- | ----------- | <tr>
| **类型标签** | | | <th style="background:#f5f7fa;color:#222;font-weight:bold;padding:8px 12px;">标签</th>
| `bug` | 缺陷或错误修复 | 修复功能异常、错误行为 | <th style="background:#f5f7fa;color:#222;font-weight:bold;padding:8px 12px;">分组</th>
| `feature` | 新功能开发 | 开发新模块、新接口 | <th style="background:#f5f7fa;color:#222;font-weight:bold;padding:8px 12px;">说明</th>
| `enhancement` | 功能改进或优化 | 性能优化、界面优化 | <th style="background:#f5f7fa;color:#222;font-weight:bold;padding:8px 12px;">用途举例</th>
| `documentation` | 文档相关 | 修改/补充文档 | </tr>
| `test` | 测试相关 | 单元测试、集成测试 | <tr>
| `question` | 需要进一步澄清 | 提问、需求澄清 | <td style="padding:6px 14px;"><code>bug</code></td>
| `wontfix` | 不会修复 | 不予处理的问题 | <td style="padding:6px 14px;">类型</td>
| **优先级标签** | | | <td style="padding:6px 14px;">缺陷或错误修复</td>
| `high` | 高优先级，需立即处理 | 紧急缺陷、重大阻塞 | <td style="padding:6px 14px;">修复功能异常、错误行为</td>
| `medium` | 中等优先级，近期处理 | 普通功能需求 | </tr>
| `low` | 低优先级，长期计划 | 次要改进、未来规划 | <tr>
<td style="padding:6px 14px;"><code>feature</code></td>
<td style="padding:6px 14px;">类型</td>
<td style="padding:6px 14px;">新功能开发</td>
<td style="padding:6px 14px;">开发新模块、新接口</td>
</tr>
<tr>
<td style="padding:6px 14px;"><code>enhancement</code></td>
<td style="padding:6px 14px;">类型</td>
<td style="padding:6px 14px;">功能改进或优化</td>
<td style="padding:6px 14px;">性能优化、界面优化</td>
</tr>
<tr>
<td style="padding:6px 14px;"><code>documentation</code></td>
<td style="padding:6px 14px;">类型</td>
<td style="padding:6px 14px;">文档相关</td>
<td style="padding:6px 14px;">修改/补充文档</td>
</tr>
<tr>
<td style="padding:6px 14px;"><code>test</code></td>
<td style="padding:6px 14px;">类型</td>
<td style="padding:6px 14px;">测试相关</td>
<td style="padding:6px 14px;">单元测试、集成测试</td>
</tr>
<tr>
<td style="padding:6px 14px;"><code>question</code></td>
<td style="padding:6px 14px;">类型</td>
<td style="padding:6px 14px;">需要进一步澄清</td>
<td style="padding:6px 14px;">提问、需求澄清</td>
</tr>
<tr>
<td style="padding:6px 14px;"><code>wontfix</code></td>
<td style="padding:6px 14px;">类型</td>
<td style="padding:6px 14px;">不会修复</td>
<td style="padding:6px 14px;">不予处理的问题</td>
</tr>
<tr>
<td style="padding:6px 14px;background:#f6fffa;"><code>high</code></td>
<td style="padding:6px 14px;background:#f6fffa;">优先级</td>
<td style="padding:6px 14px;background:#f6fffa;">高优先级，需立即处理</td>
<td style="padding:6px 14px;background:#f6fffa;">紧急缺陷、重大阻塞</td>
</tr>
<tr>
<td style="padding:6px 14px;background:#f6fffa;"><code>medium</code></td>
<td style="padding:6px 14px;background:#f6fffa;">优先级</td>
<td style="padding:6px 14px;background:#f6fffa;">中等优先级，近期处理</td>
<td style="padding:6px 14px;background:#f6fffa;">普通功能需求</td>
</tr>
<tr>
<td style="padding:6px 14px;background:#f6fffa;"><code>low</code></td>
<td style="padding:6px 14px;background:#f6fffa;">优先级</td>
<td style="padding:6px 14px;background:#f6fffa;">低优先级，长期计划</td>
<td style="padding:6px 14px;background:#f6fffa;">次要改进、未来规划</td>
</tr>
</table>
### 6.3 Issue 流程 ### 6.3 Issue 流程
@@ -282,8 +387,31 @@ flowchart LR
* **一个 Issue 只包含一个问题**：避免一个 Issue 同时涉及多个 Bug 或功能需求。 * **一个 Issue 只包含一个问题**：避免一个 Issue 同时涉及多个 Bug 或功能需求。
* **保持更新**：在处理过程中，及时补充进展，方便团队成员了解状态。 * **保持更新**：在处理过程中，及时补充进展，方便团队成员了解状态。
* **结合 Milestone**：将 Issue 归档到迭代或版本里，保证任务有明确的交付目标。 * **结合 Milestone**：将 Issue 归档到迭代或版本里，保证任务有明确的交付目标。
---
```mermaid
flowchart LR
A[创建 Issue<br/>📝] --> B[分配 Issue<br/>👤]
B --> C[处理 Issue<br/>🔨]
C --> D[关闭 Issue<br/>✅]
%% 详细说明
A -.-> A1(明确问题/需求，背景、预期、实际)
A -.-> A2(必要时截图/日志/代码)
B -.-> B1(分配给具体开发者)
B -.-> B2(复杂 Issue 可先评估拆分)
C -.-> C1(新建分支并关联 Issue)
C -.-> C2(PR 关联 Issue)
D -.-> D1(PR 合并前关闭 Issue)
D -.-> D2(未解决可重开或新建)
%% 样式
classDef main fill:#E8F6FF,stroke:#4A90E2,stroke-width:2px,rx:10,ry:10;
classDef detail fill:#F6F8FA,stroke:#B5B5B5,rx:10,ry:10;
class A,B,C,D main;
class A1,A2,B1,B2,C1,C2,D1,D2 detail;
```
## 7. 里程碑（Milestone） ## 7. 里程碑（Milestone）