diff --git a/_config.yml b/_config.yml index 9ed3d2c9..7d14a37a 100644 --- a/_config.yml +++ b/_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 diff --git a/dev/README.md b/dev/README.md new file mode 100644 index 00000000..2bda4c2d --- /dev/null +++ b/dev/README.md @@ -0,0 +1,9 @@ +--- +sort: 6 +--- + +# 开发文档 + +1. [开发环境](./environment) +2. [版本与分支](./branch) +3. [文档的编写与构建](./doc) diff --git a/dev/branch.md b/dev/branch.md new file mode 100644 index 00000000..a970fa41 --- /dev/null +++ b/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+`,其中 `YYYY` 为四位年份,`MM` 为两位月份,`` 为 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 +``` + +为避免打扰用户,若无特殊情况,稳定版每星期最多发版一次。 diff --git a/dev/doc.md b/dev/doc.md new file mode 100644 index 00000000..99b6b1be --- /dev/null +++ b/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` 复制到 `/dist/docs`,就可以在 mower 中看到文档了。 diff --git a/dev/environment.md b/dev/environment.md new file mode 100644 index 00000000..cb82034f --- /dev/null +++ b/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`) diff --git a/start/download.md b/start/download.md index 3ab2c896..a3f1e75c 100644 --- a/start/download.md +++ b/start/download.md @@ -6,7 +6,7 @@ sort: 1 **注意**:Mower 使用 Python 3.12,故不支持 Windows 7 及更早的 Windows 版本。 -## 版本发布周期 +

版本发布周期

自 2024 年 5 月起,mower 采取新的版本发布周期与命名规范:每年以春节、周年、夏活、半周年四个活动为节点,共发布四个版本,版本号以“年份+月份”命名。每个版本的支持周期为 6 个月,前 3 个月作为测试分支,开发新功能;后 3 个月作为稳定分支,只进行必要的维护与错误修复。 diff --git a/start/riic.md b/start/riic.md index 72e133ce..2a719d7d 100644 --- a/start/riic.md +++ b/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 @@ $$ --- -*施工中……* \ No newline at end of file +_施工中……_