mirror of
https://github.com/happycola233/tchMaterial-parser.git
synced 2026-10-16 20:50:33 +08:00
晨叶梦春
70 lines
3.4 KiB
Markdown
70 lines
3.4 KiB
Markdown
# 贡献者指南
|
||
|
||
感谢您愿意帮助改进本项目。这个项目面向**真实用户**，请尽量让每一次提交都保持清晰、可验证，并尊重国家中小学智慧教育平台及相关权利人的资源版权。
|
||
|
||
## 开始之前
|
||
|
||
- 提交问题前请**搜索**已有 [Issue](../../issues) 和 [Pull Request](../../pulls)，避免重复讨论。
|
||
- 发现程序无法运行、下载失败或界面异常时，请提交 [**🐛 Bug 报告**](../../issues/new?template=bug_report.yml)，并按模板补全相关信息，最好**附上错误信息截图**，以方便定位问题。
|
||
- 有新功能或改进建议时，请提交[**✨ 功能建议**](../../issues/new?template=feature_request.yml)，先说明您遇到的实际问题，再描述期望做法，这样更容易判断改动是否适合放进本项目。
|
||
- **不要**在 Issue、Pull Request、提交信息或代码等地方公开 Access Token。
|
||
|
||
## 本地开发
|
||
|
||
本项目使用 **Python 3.10 或更高版本**（`X | Y` 形式的类型注解仅在该版本及以后的版本可用）。
|
||
|
||
```sh
|
||
# 克隆项目
|
||
git clone https://github.com/happycola233/tchMaterial-parser.git
|
||
cd tchMaterial-parser
|
||
|
||
# 安装依赖
|
||
python -m pip install .
|
||
|
||
# 启动应用
|
||
python ./src/main.py
|
||
```
|
||
|
||
> [!NOTE]
|
||
> 本工具使用 **Tkinter** 构建图形界面。Windows 与 macOS 的官方 Python 通常已自带，而部分 Linux 发行版需要单独安装，例如在 Debian/Ubuntu 上执行 `sudo apt install python3-tk`。
|
||
>
|
||
> 此外，精简安装的 Linux 系统可能缺少中文字体与 Emoji 字体，此时界面上可能会出现方框等异常现象。可按需安装，例如在 Debian/Ubuntu 上执行 `sudo apt install fonts-noto-cjk fonts-noto-color-emoji`。
|
||
|
||
## 测试与检查
|
||
|
||
提交 Pull Request 前，请进行测试与检查：
|
||
|
||
```sh
|
||
# 安装开发用依赖
|
||
python -m pip install pytest flake8
|
||
|
||
# 运行测试与检查
|
||
python -m pytest
|
||
python -m flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
|
||
```
|
||
|
||
当前 CI 的静态检查只拦截语法错误、未定义变量等确定性问题，不把代码风格与中文注释行长等作为强制门槛。
|
||
|
||
格式化时请遵循仓库现有风格，如使用 **4 空格**缩进、**`snake_case`** 命名约定、字符串默认使用**双引号 `"`**、**不出现尾随空格**等。
|
||
|
||
## 打包验证
|
||
|
||
修改打包配置、资源文件或程序入口时，请额外验证 PyInstaller 构建：
|
||
|
||
```sh
|
||
python -m pip install pyinstaller
|
||
pyinstaller ./tchMaterial-parser.spec
|
||
```
|
||
|
||
构建产物位于 `dist` 目录。
|
||
|
||
## 代码与文案约定
|
||
|
||
- 本工具在设计上支持 Windows、Linux、macOS 操作系统，编写代码时应确保**跨平台兼容性**。
|
||
- 命名要**准确表达意图**；重命名变量、函数或模块时，请**同步更新**相关引用。
|
||
- 意图不明显的业务逻辑可以添加**简洁中文注释**；能从代码本身读懂的内容一般不需要注释。
|
||
- 不要为了理论上不可能发生的内部状态添加复杂兜底逻辑，校验应主要放在用户输入、文件系统、网络请求、外部 API 等**系统边界**。
|
||
- 涉及 UI 的改动，需要同时检查**浅色模式与深色模式**。
|
||
- 界面文案应直接面向**用户**，避免出现描述需求、规则或适用条件本身的元语言。
|
||
- 修改代码后，确保代码中**未出现明文 Access Token 等敏感信息**，且已执行**必要的测试与检查**。
|