# 适配新版本指南

## 本地安装

将代码库 clone 到本地后，在项目目录下执行：

```shell
pip install -e .
```

> 此处的`-e`选项启用“开发者模式”（`Development Mode`），即在安装后，对代码库的修改会立即生效，无需重新安装。可参考[Development Mode (a.k.a. “Editable Installs”) - setuptools documentation](https://setuptools.pypa.io/en/latest/userguide/development_mode.html)

（如果此命令报错，请继续阅读）

## 适配新版本

### 更改兼容 Python 版本

在`pyproject.toml`中，将`requires-python`字段的值修改为新版本范围，例如：

```toml
requires-python = ">=3.7,<3.10"
```

在`README.md`中，修改多处提及的 Python 版本范围。

### 运行测试

根据`README.md`中说明完整运行测试，并解决可能出现的问题。注意，警告信息也应当尽量减少，或与维护者商议后决定不处理。

部分测试在 Windows 及 其它系统 下测试内容、结果可能不同，但应当保证在这二者下均能通过。

由于版本更新可能破坏旧版本兼容性，适配新版本时必须保证旧版本 Python 下也可通过所有测试。可以使用 [asdf](https://asdf-vm.com/) 或 [vfox](https://vfox.lhan.me/) 等版本管理器在多个 Python 版本间切换。

仅当测试全部通过后才应当提交代码。

以下为测试的示例结果。（注意，以下列出的 测试数量、时长、文件名 等可能会随时间改变）：

```terminal
$ python -m unittest 测试.unittest.交互 测试.unittest.语法树 测试.unittest.所有用例 测试.unittest.报错 测试.unittest.Python到木兰
........
----------------------------------------------------------------------
Ran 12 tests in 2.000s

OK
```

```terminal
$ python 测试/运行所有.py
通过： 运算/加.ul
……
通过： 算法/排序/快速.ul
===================
！全部通过！
本测试针对木兰原始可执行文件与重现项目的发布版。在此之前先运行`测试/unittest`下的集成测试。
```

```terminal
$ python -m unittest 测试.unittest.原始可执行文件
.
----------------------------------------------------------------------
Ran 1 test in 53.000s

OK
```

```terminal
$ python -m unittest 测试.unittest.木兰到Python
加载文件 测试/unittest/源码生成/木兰到Python\AnnAssign.ul...
……
加载文件 测试/unittest/源码生成/木兰到Python\输出nil.ul...
得到原始木兰生成结果中...
进度: （0/11）
比较 测试/unittest/源码生成/木兰到Python\AnnAssign.ul
……
比较 测试/unittest/源码生成/木兰到Python\输出nil.ul
.
----------------------------------------------------------------------
Ran 1 test in 12.000s

OK
```

### 手工测试命令行选项功能

对于`木兰`命令行工具，应当手工测试各个选项的功能，确保其在新版本下仍能正常工作，并记录行为差异。具体测试方法可以参考[py3.8支持.md](py3.8%E6%94%AF%E6%8C%81.md#%E5%91%BD%E4%BB%A4%E8%A1%8C%E5%8F%82%E6%95%B0%E8%A1%8C%E4%B8%BA%E5%AF%B9%E6%AF%94%E6%B5%8B%E8%AF%95)。

### 更新版本、编写文档

在当前目录下，参考`py3.8支持.md`记录适配新版本的过程，包括以上数个方面的更改。

在`木兰/__init__.py`中，更新本项目的版本号。

在`CHANGELOG.md`中，记录本次更新的内容。
