开发

_config.yml

@@ -1,11 +1,11 @@
 title: arknights-mower
 lang: zh-Hans
-description: 7*24 小时不间断长草，让你忘掉这个游戏！
+description: 《明日方舟》长草助手
 
 plugins:
   - jekyll-remote-theme
 
-remote_theme: ZhaoZuohong/jekyll-rtd-theme
+remote_theme: ArkMowers/jekyll-rtd-theme
 
 readme_index:
   with_frontmatter: true

dev/README.md

@@ -0,0 +1,9 @@
+---
+sort: 6
+---
+
+# 开发文档
+
+1. [开发环境](./environment)
+2. [版本与分支](./branch)
+3. [文档的编写与构建](./doc)

dev/branch.md

@@ -0,0 +1,86 @@
+---
+sort: 2
+---
+
+# 版本与分支
+
+Mower 同时维护两个分支：测试版与稳定版。新功能的开发以及 bug 修复都测试分支上进行。然而，对代码的改动可能引入新的 bug，功能的变动也需要用户不断地学习和适应，使用测试版可能不时遇到新的 bug。对于没有精力跟踪 mower 开发进度，或希望获得稳定体验的用户，稳定版也是必不可少的。
+
+## 版本号
+
+版本号由 `arknights_mower/__init__.py` 文件中的 `__version__` 变量表示。
+
+```python
+from arknights_mower import __version__
+print(__version__)
+```
+
+Mower 使用 GitHub Actions 自动为 Windows 平台打包。打包过程中，修改版本号的步骤如下：
+
+```yaml
+- name: change version number
+  if: github.event.head_commit.message != '发版'
+  shell: bash
+  run: |
+    sed -i 's/__version__ = "\(.*\)"/__version__ = "\1+${GITHUB_SHA::7}"/g' ./arknights_mower/__init__.py
+```
+
+当提交信息是“发版”时，CI 不会修改版本号；反之，CI 会把 commit id 的前 7 位附加到版本号后面，使用加号分隔。
+
+- 测试版使用滚动更新，版本号格式为 `YYYY.MM+<commit id>`，其中 `YYYY` 为四位年份，`MM` 为两位月份，`<commit id>` 为 commit id 的前 7 位。测试版代码的 `__version__` 中只写 `YYYY.MM` 的部分，靠 CI 自动添加 commit id。
+- 稳定版使用定点更新，版本号格式为 `YYYY.MM.X`，其中 `X` 为小版本号。创建分支时 `X` 为 1，以后每次发版时，需手动增加 `X`，并将提交信息设为“发版”。
+
+## 日志页背景
+
+Mower 每年发布 4 个大版本，以新版发布前 3 个月内对基建影响最大的干员立绘作为日志页背景。
+
+- 2024.02：在版本发布前，mower 实装了新的肥鸭充能策略，所以选择菲亚梅塔。
+- 2024.05：从春节活动开始到周年活动前，对基建影响最大的干员是阿罗玛。
+- 2024.08：预计为乌尔比安。
+
+## 如何开发测试版
+
+测试版的开发一直在 dev_shawn 分支进行。在发布新版本时，只需要对版本号做出修改。例如 2024 年夏活更新后，将 dev_shawn 分支的版本号从 `2024.05` 改为 `2024.08` 即可。
+
+## 如何维护稳定版
+
+为保证稳定版的特性相对稳定，稳定版只接受添加新干员和 bug 修复。除非修复 bug 需要，否则不要添加新的功能。
+
+稳定版的代码与测试版有所不同，所以在发布新版本时，需要基于当前的测试版新建稳定版分支，然后修改测试分支的版本号。例如 2024 年夏活更新时，稳定分支 2024.02 停止维护，基于 dev_shawn 分支新建 2024.05 分支，并把 2024.05 分支的版本号从 `2024.05` 改为 `2024.05.1`，作为新的稳定版发版。后续在稳定分支上进行若干改动后，将版本号由 `2024.05.1` 改为 `2024.05.2` 并发版，以此类推。
+
+虽然稳定版的代码在单独的分支，但除修改版本号外，出于以下原因，应尽量避免直接向稳定分支提交代码：
+
+1. 直接向稳定分支提交的代码，没有经过测试，可能引入新的 bug；
+2. Mower 的开发力量有限，同时维护两个分支耗费的精力太多，在当前阶段是不现实的；
+3. 稳定分支是基于测试分支创建的，在绝大部分情况下，对于同一个 bug，两个分支可以使用相同的方式进行修复。
+
+因此，更恰当的做法是，将提交推送到测试分支，经过用户的充分测试后，以 cherry-pick 的方式，将修改反向移植到稳定分支。
+
+```mermaid
+%%{init: {'gitGraph': {'mainBranchName': 'dev_shawn'}}}%%
+gitGraph
+
+commit
+
+branch 2024.02
+commit id: "2024.02.1" tag: "2024.02.1"
+
+checkout dev_shawn
+commit id: "2024.05"
+commit
+commit id: "bug fix"
+
+checkout 2024.02
+cherry-pick id: "bug fix"
+
+checkout dev_shawn
+commit
+
+checkout 2024.02
+commit id: "2024.02.2" tag: "2024.02.2"
+
+checkout dev_shawn
+commit
+```
+
+为避免打扰用户，若无特殊情况，稳定版每星期最多发版一次。

dev/doc.md

@@ -0,0 +1,29 @@
+---
+sort: 3
+---
+
+# 文档的编写与构建
+
+文档使用 Jekyll 框架，源码在 [doc-pages 分支](https://github.com/ArkMowers/arknights-mower/tree/doc-pages)。
+
+预览与构建文档，需要安装 Ruby 3.3 和 Bundler。
+
+## 安装依赖
+
+```bash
+bundle install
+```
+
+## 预览文档
+
+```bash
+bundle exec jekyll serve
+```
+
+## 构建文档
+
+```bash
+bundle exec jekyll build -b /docs
+```
+
+将生成的 `_site` 复制到 `<mower 文件夹>/dist/docs`，就可以在 mower 中看到文档了。

dev/environment.md

@@ -0,0 +1,17 @@
+---
+sort: 1
+---
+
+# 开发环境
+
+参照《[从源码运行 arknights-mower](https://blog.zhaozuohong.vip/2023/08/02/run-arknights-mower-from-source/)》搭建开发环境。
+
+## Python 版本
+
+- 2024.02 分支需要 Python 3.8
+- dev_shawn 分支需要 Python 3.12
+
+## 自动格式化
+
+- Python 代码使用 Ruff 自动格式化（已配置 `ruff.toml`）
+- 前端代码使用 Prettier 自动格式化（已配置 `ui/.prettierrc.json`）

start/download.md

@@ -6,7 +6,7 @@ sort: 1
 
 **注意**：Mower 使用 Python 3.12，故不支持 Windows 7 及更早的 Windows 版本。
 
-## 版本发布周期
+<h2 id="release-cycle">版本发布周期</h2>
 
 自 2024 年 5 月起，mower 采取新的版本发布周期与命名规范：每年以春节、周年、夏活、半周年四个活动为节点，共发布四个版本，版本号以“年份+月份”命名。每个版本的支持周期为 6 个月，前 3 个月作为测试分支，开发新功能；后 3 个月作为稳定分支，只进行必要的维护与错误修复。
 

start/riic.md

@@ -2,13 +2,13 @@
 sort: 2
 ---
 
-# 排班表编写指南
+# 基建功能介绍
 
-新手建议阅读《[Mower 简明教程](https://blog.zhaozuohong.vip/2024/05/10/mower-guide/tutorial/)》，加入 QQ 频道 [ArkMower（频道号：2r118jwue4）](https://pd.qq.com/s/5t91c3gx9)交流基建心得。
+基建是 mower 的核心功能。然而，用 mower ≠ 产出高，玩家只有提高自身的基建理解，才能充分发挥 mower 的作用，取得更高的收益。因此，本篇文档先讲解必要的基建知识，然后说明 mower 的各项基建功能对于提高产出的作用。
 
-## 怎样提高钱书产出
+新手建议阅读《[Mower 简明教程](https://blog.zhaozuohong.vip/2024/05/10/mower-guide/tutorial/)》，加入 QQ 频道 [ArkMower（频道号：2r118jwue4）](https://pd.qq.com/s/5t91c3gx9)交流基建心得。
 
-### 产出计算教程
+## 产出计算教程
 
 不了解产出计算的玩家，建议阅读以下内容：
 
@@ -18,7 +18,9 @@ sort: 2
 - [无人机相关计算](https://blog.zhaozuohong.vip/2023/12/04/mower-guide/1-4/)
 - [心情相关计算](https://blog.zhaozuohong.vip/2023/12/06/mower-guide/1-5/)
 
-### 衡量基建钱书产出的指标
+这几篇博客虽然提到了 mower，但是涉及的原理与策略完全由基建自身的机制得出，并不仅限于 mower。
+
+## 衡量基建钱书产出的指标
 
 很多玩家试图找到一个衡量基建钱书产出的指标。从生产的角度分析，这实质上是为订单、赤金、经验设置一组系数。比如：
 
@@ -79,7 +81,7 @@ $$
 
 总而言之，对于大量刷钱书的情况，“总和”是恰当的指标；对于不刷钱书的情况，一维的衡量基建钱书产出的指标难免与基建生产过程发生脱节，这样的指标没有任何意义。
 
-### 比较钱书产出的正确方法
+## 比较钱书产出的正确方法
 
 对于大量刷钱书的情况，比较“总和”指标即可。
 
@@ -95,7 +97,7 @@ $$
 
 在不同的生产方案时，如果遇到涉及转化的情况，应该紧密联系基建生产过程，将涉及转化的情况转换为能够直接比较的情况，然后进行比较。
 
-### （不刷钱书）使用 mower 提高基建产出
+## （不刷钱书）使用 mower 提高基建产出
 
 基建产出为单位产出、平均效率、时间三者的乘积：
 
@@ -109,13 +111,13 @@ $$
 \frac{\text{基建产出}}{\text{时间}} = \text{单位产出} \times \text{平均效率}
 $$
 
-#### 单位产出
+### 单位产出
 
 对于制造站和发电站，单位产出是固定的；但对于贸易站，单位产出受设施等级、但书、龙舌兰、裁缝等因素影响。
 
 Mower 支持跑单操作，与不跑单相比，贸易站的单位产出得到了大幅提升。如果适当降低贸易站的平均效率、提高制造站平均效率（例如在 2 电站布局下降级贸易站、升级制造站；3 电站布局使用 243 / 153 互切），就能实现基建钱书产出的均衡提升。
 
-#### 平均效率
+### 平均效率
 
 平均效率由设施效率、干员效率、工作时间占比三项组成：
 
@@ -137,4 +139,4 @@ $$
 
 ---
 
-*施工中……*
+_施工中……_