Update developer doc

RubyMetric · Dec 27, 2024 · 7838284 · 7838284
1 parent 0a51fa4
commit 7838284
Show file tree

Hide file tree

Showing 6 changed files with 49 additions and 33 deletions.
diff --git a/README.md b/README.md
@@ -25,14 +25,16 @@
 
 ## 🤝 协作与贡献
 
+从开发到提交贡献，全流程文档，请参考目录 [doc](./doc/)
+
 > [!TIP]
 > **`chsrc` 不仅是一个命令行工具，同时也是一个换源框架，它甚至使你能够在不了解C语言的情况下编写出新的换源方法(recipe)。** 给新软件添加换源方法总共分几步？[Write A Recipe Even If You Don't Know C](./doc/Write-A-Recipe-Even-If-You-Dont-Know-C.md)
 
 > [!NOTE]
 > **`chsrc` 可换源 60+ 目标。每个人仅仅贡献和维护自己熟悉的部分，回报是得到其他所有领域专家的帮助**。欢迎对 GitHub、Gitee 协作不熟悉的人以此为契机学习参与贡献, 欢迎任何编程初学者参与贡献，作者可提供一定的 [贡献指导](https://github.com/RubyMetric/chsrc/discussions/50)。
 
 > [!IMPORTANT]
-> [招募 Recipe 维护者](https://github.com/RubyMetric/chsrc/issues/130)
+> [招募 recipe 维护者](https://github.com/RubyMetric/chsrc/issues/130)
 
 <br>
 
@@ -410,12 +412,6 @@ chsrc set conda  | anaconda
 
 <br>
 
-## 🛠️ 开发
-
-请参考 [./doc/Develop.md](./doc/Develop.md)
-
-<br>
-
 ## 📝 许可证
 
 - `chsrc` 主程序采用 `GPL-3.0-or-later` 许可证，保证该软件的永久自由
@@ -443,7 +439,7 @@ chsrc set conda  | anaconda
 
 你是否因为使用 `chsrc` 而节省了时间和精力 or whatever?
 
-<img src="https://raw.githubusercontent.com/ccmywish/support-my-oss-work/main/wechat.png" alt="wechat" style="width:300px;"/>
+<img src="https://raw.githubusercontent.com/ccmywish/support-my-oss-work/main/wechat.png" alt="wechat-reward" style="width:300px;"/>
 
 <br>
 

diff --git a/doc/Develop.md → doc/01-Develop.md b/doc/Develop.md → doc/01-Develop.md
@@ -2,7 +2,7 @@
  ! SPDX-License-Identifier: GFDL-1.3-or-later
  ! -------------------------------------------------------------
  ! Doc Type      : Markdown
- ! Doc Name      : 01-Develop.md
+ ! Doc Name      : Develop.md
  ! Doc Authors   : Aoran Zeng <[email protected]>
  ! Contributors  :  Nul None  <[email protected]>
  !               |
@@ -21,6 +21,8 @@
 $ git clone https://gitee.com/RubyMetric/chsrc.git -b dev
 ```
 
+关于分支的说明，可参考 [./03-CONTRIBUTING.md](./03-CONTRIBUTING.md)
+
 <br>
 
 ## 编译运行
@@ -55,6 +57,6 @@ $ make clean
 
 ## 提交 PR
 
-关于分支的说明以及如何提交代码，请参考 [./CONTRIBUTING.md](./CONTRIBUTING.md)
+关于分支的说明以及如何提交代码，请参考 [./03-CONTRIBUTING.md](./03-CONTRIBUTING.md)
 
 <br>
diff --git a/...Write-A-Recipe-Even-If-You-Dont-Know-C.md → ...Write-A-Recipe-Even-If-You-Dont-Know-C.md b/...Write-A-Recipe-Even-If-You-Dont-Know-C.md → ...Write-A-Recipe-Even-If-You-Dont-Know-C.md
@@ -2,11 +2,12 @@
  ! SPDX-License-Identifier: GFDL-1.3-or-later
  ! -------------------------------------------------------------
  ! Doc Type      : Markdown
+ ! Doc Name      : Write-A-Recipe-Even-If-You-Dont-Know-C.md
  ! Doc Authors   : Aoran Zeng <[email protected]>
  ! Contributors  :  Nul None  <[email protected]>
  !               |
  ! Created On    : <2024-08-19>
- ! Last Modified : <2024-12-23>
+ ! Last Modified : <2024-12-27>
  ! ---------------------------------------------------------- -->
 
 # Write A Recipe Even If You Don't Know C
@@ -17,7 +18,7 @@
 
 <br>
 
-我鼓励你为新的软件添加换源支持，因为通过 `chsrc` 这将非常简单，你的贡献也将非常有价值。理论上每一个 `recipe` 都需要有专人长时间维护。
+我鼓励你为新的软件添加换源支持，因为通过 `chsrc` 这将非常简单，你的贡献也将非常有价值。理论上每一个 `recipe` 都需要有专人长时间维护 ([招募](https://github.com/RubyMetric/chsrc/issues/130))。
 
 1. 本项目采用 `GPLv3+` 协议，是真正的**自由软件**，而非仅仅是开源软件
 2. 代码规范灵活遵循 `GNU` 标准（若标准干扰了可维护性，则并不采纳）
@@ -39,12 +40,6 @@
 
 <br>
 
-# 贡献指导
-
-若有任何问题，可在 [GitHub discussions](https://github.com/RubyMetric/chsrc/discussions) 中询问和讨论
-
-<br>
-
 # 基本概念
 
 1. `target`: 所要换源的目标
@@ -64,26 +59,34 @@
 
 <br>
 
-# 编写recipe步骤
+# 编写 `recipe` 步骤
+
+1. 确定你要编写的 `target` 的标准名称，创建 `Target-Name.c` 文件
+
+    大小写需严格按官方，若名称包含空格，需使用 `-` 代替空格
+
+2. 根据类别将上述文件放在 `recipe/` 目录的某个子目录中
 
-1. 务必使用 `dev` 分支
+3. 复制 [recipe template] 的内容到上述文件中，并替换 `<...>` 占位符
 
-2. 在 `recipe` 目录中根据类别添加新文件，该文件可基于其它 `recipe` 或 [recipe template]
+4. 参考现有 `recipe` 的写法
 
-3. 最好的参照物是 [ruby.c recipe](../src/recipe/lang/Ruby.c)
+    1. 看一眼就能上手的参照物是 [PHP recipe](../src/recipe/lang/PHP.c)
+    2. 最好的参照物是 [Ruby recipe](../src/recipe/lang/Ruby.c)
+    3. 组换源参照物是 [Python Group recipe](../src/recipe/lang/Python/Python.c)
 
-4. 在各大镜像站寻找可用源；可以额外补充镜像站
+5. 在 [Wiki] 中记录的镜像站中寻找可用源；可以额外补充镜像站
 
-    并创建或更新对应 `target` 的镜像站可用状态Wiki页: https://github.com/RubyMetric/chsrc/wiki
+    并创建或更新对应 `target` 的镜像站可用状态 [Wiki] 页
 
-5. 可以使用这些函数:
+6. 可以使用这些函数:
 
     1. `framework/core.c` 中以 `chsrc_` 开头的所有函数或宏
     2. `xy.h` 中以 `xy_` 开头的所有函数或宏
 
-6. 在 `recipe/menu.c` 中添加用户可以使用的 `target` 别名
+7. 在 `recipe/menu.c` 中添加用户可以使用的 `target` 别名
 
-7. 构建并运行 `chsrc set <target>` 测试，若无问题可提交 Pull Request
+8. [编译、运行、测试 (how?)](./01-Develop.md)，若无问题可提交 Pull Request
 
 <br>
 
@@ -100,3 +103,4 @@
 <br>
 
 [recipe template]: ../src/recipe/recipe-template.c
+[Wiki]: https://github.com/RubyMetric/chsrc/wiki
diff --git a/doc/CONTRIBUTING.md → doc/03-CONTRIBUTING.md b/doc/CONTRIBUTING.md → doc/03-CONTRIBUTING.md
@@ -1,3 +1,15 @@
+<!-- -----------------------------------------------------------
+ ! SPDX-License-Identifier: GFDL-1.3-or-later
+ ! -------------------------------------------------------------
+ ! Doc Type      : Markdown
+ ! Doc Name      : 03-CONTRIBUTING.md
+ ! Doc Authors   : Aoran Zeng <[email protected]>
+ ! Contributors  :  Nul None  <[email protected]>
+ !               |
+ ! Created On    : <2024-12-13>
+ ! Last Modified : <2024-12-27>
+ ! ---------------------------------------------------------- -->
+
 # 贡献说明
 
 ## 分支
@@ -24,7 +36,7 @@
 （1）
 
 1. **如果你是 recipe director，则你完全负责这个 recipe，如果你拥有写权限，你可以直接推送代码到 `dev` 分支**
-2. 如果你是 recipe maintainer，则你需要参考 [MAINTAINERS.md](./MAINTAINERS.md)，如果只有你一个人，且你拥有写权限，你可以直接推送代码。如果有多人，则需要提一个 issue，介绍方案，然后 @ 所有 maintainer 来 review
+2. 如果你是 recipe maintainer，则你需要参考 [04-MAINTAINERS.md](./04-MAINTAINERS.md)，如果只有你一个人，且你拥有写权限，你可以直接推送代码。如果有多人，则需要提一个 issue，介绍方案，然后 @ 所有 maintainer 来 review
 
 ---
 

diff --git a/doc/MAINTAINERS.md → doc/04-MAINTAINERS.md b/doc/MAINTAINERS.md → doc/04-MAINTAINERS.md
@@ -13,7 +13,7 @@
 
 2. **Maintainers**
 
-    维护者：实现和持续维护 recipe，需要和 Director 一起 review 代码。可参考 [CONTRIBUTIING.md](./CONTRIBUTING.md) 了解项目是如何进行提交和审阅代码的
+    维护者：实现和持续维护 recipe，需要和 Director 一起 review 代码。可参考 [03-CONTRIBUTING.md](./03-CONTRIBUTING.md) 了解项目是如何进行提交和审阅代码的
 
 
 3. **Observers**

diff --git a/doc/README.md b/doc/README.md
@@ -12,12 +12,14 @@
 
 # 文档说明
 
+**注：这些不是用户手册，而是开发者文档**
+
 E2E (End-to-End) 开发流程:
 
-1. 开发环境准备，如何编译和测试，请参考 [./Develop.md](./Develop.md)
-2. 如何编写一个具体的 recipe，请参考 [./Write-A-Recipe-Even-If-You-Dont-Know-C.md](./Write-A-Recipe-Even-If-You-Dont-Know-C.md)
-3. 直接推送还是提交 PR，请参考 [./CONTRIBUTING.md](./CONTRIBUTING.md)
-4. 找谁来审阅 PR，请参考 [./MAINTAINERS.md](./MAINTAINERS.md)
+1. 开发环境准备，如何编译和测试，请参考 [./01-Develop.md](./01-Develop.md)
+2. 如何编写一个具体的 recipe，请参考 [./02-Write-A-Recipe-Even-If-You-Dont-Know-C.md](./02-Write-A-Recipe-Even-If-You-Dont-Know-C.md)
+3. 直接推送还是提交 PR，请参考 [./03-CONTRIBUTING.md](./03-CONTRIBUTING.md)
+4. 找谁来审阅 PR，请参考 [./04-MAINTAINERS.md](./04-MAINTAINERS.md)
 
 <br>