Skip to content

Commit af7e361

Browse files
Charliechen114514Charliechen114514
authored
feat: dev style entrance before start new dev on content (#48)
1 parent c1d5dd1 commit af7e361

9 files changed

Lines changed: 317 additions & 0 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -322,6 +322,8 @@ QA 不替代正文，只负责解答常见分叉问题和高频误区。
322322

323323
新增文章前请检查 frontmatter、索引、内部链接、代码块和翻译状态。本地质量命令和 CI workflow 应保持可对应：
324324

325+
项目日常维护和网站迭代节奏见 [项目开发 / 网站迭代节奏](documents/community/dev/01-iteration-cadence.md)。
326+
325327
- Markdown link check
326328
- Frontmatter validation
327329
- English coverage

‎README.en.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212

1313
![C++](https://img.shields.io/badge/C%2B%2B-11%20%7C%2014%20%7C%2017%20%7C%2020%20%7C%2023-blue?logo=c%2B%2B)
1414
![Release](https://img.shields.io/github/v/release/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP)
15+
![Tag](https://img.shields.io/github/v/tag/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP?sort=semver&label=tag)
1516
![License](https://img.shields.io/github/license/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP)
1617
![Build](https://img.shields.io/github/actions/workflow/status/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP/deploy.yml?branch=main)
1718

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212

1313
![C++](https://img.shields.io/badge/C%2B%2B-11%20%7C%2014%20%7C%2017%20%7C%2020%20%7C%2023-blue?logo=c%2B%2B)
1414
![Release](https://img.shields.io/github/v/release/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP)
15+
![Tag](https://img.shields.io/github/v/tag/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP?sort=semver&label=tag)
1516
![License](https://img.shields.io/github/license/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP)
1617
![Build](https://img.shields.io/github/actions/workflow/status/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP/deploy.yml?branch=main)
1718

‎documents/community/dev/01-iteration-cadence.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
title: "网站迭代节奏"
3+
description: "Tutorial_AwesomeModernCPP 的内容产出、站点维护、PR/Issue 处理和发版节奏"
4+
chapter: 1
5+
order: 1
6+
tags: ["工程实践"]
7+
---
8+
9+
# 网站迭代节奏
10+
11+
Tutorial_AwesomeModernCPP 的迭代以内容产出为主，版本号用于度量内容推进幅度。站点维护、PR 和 Issue 处理服务于主线内容，不反过来接管主线节奏。
12+
13+
## 基本节拍
14+
15+
维护者通常每 2 到 3 天进行一次轻量迭代。每轮只绑定一个主要目标：
16+
17+
- 完成一组相关内容。
18+
- 修复一批影响阅读的问题。
19+
- 补齐某个章节的代码、链接或翻译。
20+
- 处理已经明确可行动的 PR 或 Issue。
21+
22+
一轮迭代不追求覆盖所有方向。卷级路线、长期候选和远期主题继续放在 `todo/`，不要把单篇文章级临时想法拆成新的治理文件。
23+
24+
## 单轮维护流程
25+
26+
每轮维护按以下顺序推进：
27+
28+
1. 查看当前 TODO 中的 P0/P1 目标，选定一个主要内容目标。
29+
2. 快速检查 Issue 和 PR，只处理明确可行动、影响当前版本或阻塞读者的问题。
30+
3. 完成本轮内容、示例代码、索引和必要的英文同步。
31+
4. 运行与改动范围匹配的质量检查。
32+
5. 如果变化对读者可感知，更新 changelog 或准备下一个版本条目。
33+
34+
PR 和 Issue 每轮至少检查一次。紧急问题可以随时插队，例如站点无法构建、重要页面 404、示例代码严重误导读者、外部贡献需要快速反馈。
35+
36+
## 版本节奏
37+
38+
版本号描述变化幅度，而不是强行驱动写作节奏。
39+
40+
- patch：修错、链接、站点修复、低风险文本修订。
41+
- minor：一个卷或专题明显推进，读者能感知新的学习路径或完整能力。
42+
- major：TODO 结构、站点架构或内容体系发生大调整。
43+
44+
patch 可以按需发布。minor 通常以 2 到 4 周为一个观察窗口，只有当某个专题形成完整增量时再发布。major 应保持克制，避免频繁改变读者和贡献者的入口认知。
45+
46+
## Tag 与 Release
47+
48+
tag 和 GitHub Release 分开使用。tag 用来标记轻量维护节点，让读者通过 README 徽章感知项目确实在持续变化；GitHub Release 只用于读者值得专门关注的内容型版本。
49+
50+
- patch 级修复可以只打 tag，不必创建 GitHub Release。
51+
- minor 级专题推进通常应创建 Release，并配套 changelog。
52+
- major 级结构调整必须创建 Release，并解释迁移影响。
53+
54+
这样可以保留项目活跃度信号，同时避免 Release 轰炸。
55+
56+
## 完成定义
57+
58+
一次内容迭代完成时，应尽量满足以下条件：
59+
60+
- 正文可以独立阅读，术语和标准版本标注清楚。
61+
- 相关卷首页、章节索引或导航入口已更新。
62+
- 文章中的示例代码可以编译，或明确说明平台和工具链限制。
63+
- 中文和英文关键页面保持同步；社区初刊和低优先级长文可延后翻译。
64+
- 内部链接可通过检查，生产构建可通过。
65+
66+
如果本轮只做局部修复，可以只运行相关检查；如果准备发版，应运行完整发布前检查。
67+
68+
## PR 和 Issue 处理
69+
70+
Issue 负责可行动问题，Discussion 负责开放式学习讨论，PR 负责具体修改。
71+
72+
处理优先级如下：
73+
74+
1. 阻塞构建、部署或主要阅读路径的问题。
75+
2. 已有 PR 中清晰、低风险、容易合并的修复。
76+
3. 与当前迭代主题直接相关的内容建议。
77+
4. 可沉淀为 QA、附录或后续 TODO 的学习问题。
78+
79+
学习问题不直接塞进 Issue 列表；高质量讨论可以整理为 FAQ、附录或正文链接。
80+
81+
## Changelog 原则
82+
83+
changelog 应写读者可感知的变化，而不是简单罗列文件数量。
84+
85+
推荐记录：
86+
87+
- 新增或完成了哪条学习路径。
88+
- 哪些示例现在可以运行或验证。
89+
- 哪些站点入口、搜索、导航、社区流程得到改善。
90+
- 哪些贡献者帮助修正了具体问题。
91+
92+
文件数、行数和提交数可以作为辅助数据，但不应替代变化说明。
93+
94+
## 常用检查
95+
96+
日常迭代按改动范围选择检查：
97+
98+
```bash
99+
pnpm check:links
100+
python3 scripts/validate_frontmatter.py
101+
python3 scripts/check_quality.py documents/
102+
python3 scripts/build_examples.py --host
103+
```
104+
105+
发版前建议运行：
106+
107+
```bash
108+
pnpm check:links
109+
pnpm build
110+
pnpm coverage:update
111+
python3 scripts/validate_frontmatter.py
112+
python3 scripts/check_quality.py documents/
113+
python3 scripts/build_examples.py --host
114+
```
115+
116+
如果改动 STM32 示例，再运行：
117+
118+
```bash
119+
python3 scripts/build_examples.py --stm32
120+
```

‎documents/community/dev/index.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
title: "项目开发"
3+
description: "社区协作下的项目维护节奏、开发日志、发布治理和站点演进记录"
4+
---
5+
6+
# 项目开发
7+
8+
这里记录 Tutorial_AwesomeModernCPP 自身的开发、维护和发布节奏。它挂靠在社区区下，因为这些流程直接服务于内容协作、PR/Issue 处理和站点长期维护。
9+
10+
本区不替代 `todo/`、`changelogs/` 或 `CONTRIBUTING.md`：
11+
12+
- `todo/` 记录内容路线和卷级规划。
13+
- `changelogs/` 记录已经发布的版本变化。
14+
- `CONTRIBUTING.md` 记录投稿、审阅和质量规则。
15+
- `community/dev/` 记录维护者如何推进网站和内容迭代。
16+
17+
## 开发记录
18+
19+
<ChapterNav variant="main">
20+
<ChapterLink num="1" href="01-iteration-cadence">网站迭代节奏</ChapterLink>
21+
</ChapterNav>
22+
23+
## 使用原则
24+
25+
项目开发区优先沉淀长期有效的维护方法，而不是临时任务清单。短期任务仍进入对应卷级 TODO，版本变更仍进入 changelog。

‎documents/community/index.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ description: "社区来稿、初刊文章与已审阅收录内容"
1414
<ChapterNav variant="main">
1515
<ChapterLink num="1" href="incoming/">社区来稿初刊</ChapterLink>
1616
<ChapterLink num="2" href="articles/">已审阅收录</ChapterLink>
17+
<ChapterLink num="3" href="dev/">项目开发</ChapterLink>
1718
</ChapterNav>
1819

1920
## 流转方式
@@ -55,3 +56,5 @@ description: "社区来稿、初刊文章与已审阅收录内容"
5556
- 作者同意公开展示，并允许维护者进行必要编辑。
5657

5758
学习问题、路线讨论和开放式建议请优先使用 GitHub Discussions；明确的内容提案或投稿主题可以使用 GitHub Issue。
59+
60+
项目自身的维护节奏、站点迭代和发布度量记录在 [项目开发](dev/) 中。

‎documents/en/community/dev/01-iteration-cadence.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
title: "Site Iteration Cadence"
3+
description: "Content production, site maintenance, PR/Issue handling, and release cadence for Tutorial_AwesomeModernCPP"
4+
chapter: 1
5+
order: 1
6+
tags: ["工程实践"]
7+
---
8+
9+
# Site Iteration Cadence
10+
11+
Tutorial_AwesomeModernCPP is driven primarily by content production. Version numbers measure the size of content progress. Site maintenance, PRs, and Issues support the main content path instead of taking it over.
12+
13+
## Basic Rhythm
14+
15+
Maintainers usually run a lightweight iteration every 2 to 3 days. Each iteration should have one main goal:
16+
17+
- Finish a related group of content.
18+
- Fix a batch of reading problems.
19+
- Complete code, links, or translations for a chapter.
20+
- Handle clearly actionable PRs or Issues.
21+
22+
One iteration does not need to cover every direction. Volume roadmaps, long-term candidates, and future themes remain in `todo/`. Temporary article-level ideas should not become new governance files.
23+
24+
## Per-Iteration Flow
25+
26+
Each maintenance iteration follows this order:
27+
28+
1. Review the current P0/P1 TODO goals and choose one main content target.
29+
2. Quickly check Issues and PRs, handling only items that are actionable, release-relevant, or reader-blocking.
30+
3. Complete the content, example code, indexes, and required English/Chinese sync for the iteration.
31+
4. Run the quality checks that match the change scope.
32+
5. If the change is reader-visible, update the changelog or prepare the next release entry.
33+
34+
PRs and Issues should be checked at least once per iteration. Urgent problems may interrupt the cycle, such as broken site builds, important 404 pages, misleading example code, or external contributions that need quick feedback.
35+
36+
## Version Cadence
37+
38+
Version numbers describe the size of change; they should not force the writing schedule.
39+
40+
- patch: typo fixes, links, site fixes, and low-risk text corrections.
41+
- minor: one volume or topic has clearly moved forward, giving readers a new learning path or complete capability.
42+
- major: TODO structure, site architecture, or the content system changes substantially.
43+
44+
Patch releases can ship as needed. Minor releases usually use a 2 to 4 week observation window and ship only when a topic forms a complete increment. Major releases should stay rare to avoid repeatedly changing reader and contributor entry points.
45+
46+
## Tags and Releases
47+
48+
Tags and GitHub Releases are used separately. Tags mark lightweight maintenance checkpoints so readers can see ongoing progress through the README badge. GitHub Releases are reserved for content versions that readers should explicitly notice.
49+
50+
- Patch-level fixes may be tagged without creating a GitHub Release.
51+
- Minor topic increments should usually create a Release with a changelog.
52+
- Major structural changes must create a Release and explain migration impact.
53+
54+
This keeps project activity visible without overwhelming readers with Release notifications.
55+
56+
## Definition of Done
57+
58+
A content iteration should usually satisfy these conditions:
59+
60+
- The article can be read independently, with terms and C++ standard versions clearly marked.
61+
- Related volume pages, chapter indexes, or navigation entries are updated.
62+
- Example code in the article can compile, or platform/toolchain limits are explicitly stated.
63+
- Key Chinese and English pages stay in sync; community drafts and low-priority long-form notes may be translated later.
64+
- Internal links pass checks, and the production build succeeds.
65+
66+
For local fixes, run only the relevant checks. Before a release, run the full pre-release checks.
67+
68+
## PR and Issue Handling
69+
70+
Issues are for actionable problems, Discussions are for open-ended learning conversations, and PRs are for concrete changes.
71+
72+
Handle items in this order:
73+
74+
1. Problems that block builds, deployment, or major reading paths.
75+
2. Clear, low-risk fixes already submitted as PRs.
76+
3. Content suggestions directly related to the current iteration theme.
77+
4. Learning questions that can become QA entries, appendix material, or future TODO items.
78+
79+
Learning questions should not fill the Issue list directly. High-quality discussions can be summarized into FAQ entries, appendix pages, or links from the main content.
80+
81+
## Changelog Principles
82+
83+
The changelog should describe reader-visible changes, not just file counts.
84+
85+
Prefer recording:
86+
87+
- Which learning path was added or completed.
88+
- Which examples can now run or be verified.
89+
- Which site entries, search behavior, navigation, or community flows improved.
90+
- Which contributors helped fix specific problems.
91+
92+
File counts, line counts, and commit counts can be supporting data, but they should not replace the explanation of what changed.
93+
94+
## Common Checks
95+
96+
Choose checks by change scope during daily maintenance:
97+
98+
```bash
99+
pnpm check:links
100+
python3 scripts/validate_frontmatter.py
101+
python3 scripts/check_quality.py documents/
102+
python3 scripts/build_examples.py --host
103+
```
104+
105+
Before a release, run:
106+
107+
```bash
108+
pnpm check:links
109+
pnpm build
110+
pnpm coverage:update
111+
python3 scripts/validate_frontmatter.py
112+
python3 scripts/check_quality.py documents/
113+
python3 scripts/build_examples.py --host
114+
```
115+
116+
If STM32 examples changed, also run:
117+
118+
```bash
119+
python3 scripts/build_examples.py --stm32
120+
```

‎documents/en/community/dev/index.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
title: "Development"
3+
description: "Project maintenance cadence, development notes, release governance, and site evolution records under community collaboration"
4+
---
5+
6+
# Development
7+
8+
This section documents how Tutorial_AwesomeModernCPP itself is developed, maintained, and released. It lives under the community section because these practices support content collaboration, PR/Issue handling, and long-term site maintenance.
9+
10+
It does not replace `todo/`, `changelogs/`, or `CONTRIBUTING.md`:
11+
12+
- `todo/` tracks content roadmaps and volume-level plans.
13+
- `changelogs/` records changes that have already shipped.
14+
- `CONTRIBUTING.md` defines contribution, review, and quality rules.
15+
- `community/dev/` explains how maintainers move the site and content forward.
16+
17+
## Development Notes
18+
19+
<ChapterNav variant="main">
20+
<ChapterLink num="1" href="01-iteration-cadence">Site Iteration Cadence</ChapterLink>
21+
</ChapterNav>
22+
23+
## Principles
24+
25+
The development section is for durable maintenance practices, not temporary task lists. Short-term work remains in the relevant volume TODO, and released changes remain in the changelog.

‎documents/en/community/index.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
title: "Community"
3+
description: "Community articles, reviewed submissions, and project development notes"
4+
---
5+
6+
# Community
7+
8+
This section collects community submissions and project maintenance notes for Tutorial_AwesomeModernCPP.
9+
10+
Community content does not have to become part of the main tutorial volumes immediately. Contributors can submit Markdown first, maintainers can perform basic checks, and the content can later move into reviewed articles or a main tutorial chapter.
11+
12+
## Sections
13+
14+
<ChapterNav variant="main">
15+
<ChapterLink num="1" href="dev/">Development</ChapterLink>
16+
</ChapterNav>
17+
18+
## Development Notes
19+
20+
Project maintenance cadence, site iteration, and release measurement are documented in [Development](dev/).

0 commit comments

Comments
 (0)