Skip to content

Latest commit

 

History

History
95 lines (57 loc) · 4.63 KB

CONTRIBUTING.md

File metadata and controls

95 lines (57 loc) · 4.63 KB
Raw

Code Contribution Guidelines

注：简体中文版在本文下方。

Thank you very much for your willingness to contribute to the Py2exe-GUI project, please read the following and follow some ground rules in order to keep the project in good shape for rapid development.

Before Writing Code

If you have any thoughts that involve more than a few dozen lines of code, I highly recommend you to submit an issue first talking about the stuff you want to implement. It's a good idea to discuss whether we want to do it before you put a lot of effort into it, and it also ensures that we're not duplicating work.

Coding

Prepare the development environment

Development environment is more complicated than use environment, ensure that you have installed Python 3.11+ and Poetry. Then use Poetry to create and install the development environment:

cd Py2exe-GUI
poetry install --with dev --extras "AddOns"

You also need to install a git hook via pre-commit:

pre-commit install

Code Style

  • In general, new and modified code should be close to the style of the original code. Try to make the code readable.
  • Please format the code using Black to ensure that all code styles are consistent with the project.
  • Please add sufficient type annotations to the code for your code. This allows the code to pass mypy checks without reporting errors.
  • Please add docstrings or comments to modules, classes, functions/methods, properties, etc. to ensure clarity and readability.

Documentation

If you implement some new features, you should consider adding the appropriate documentation to the docs/ directory, or modifying README.md as appropriate to elaborate.

Tests

The Py2exe-GUI project does not have any tests at the moment due to my limited programming skills as well as the fact that automated tests are not easily implemented for GUI programs. If you want to add some test code, please create tests/ directory in the root directory of the whole project and put the test code in it.

Pull Request

Do a pull request to the main branch of muziing/Py2exe-GUI, and I will review the code and give feedbacks as soon as possible.

代码贡献指南

非常感谢你愿意为 Py2exe-GUI 项目提供贡献，请阅读以下内容，遵守一些基本规则，以便项目保持良好状态快速发展。

开始编码之前

如果你准备对代码进行超过数十行的修改或新增，我强烈建议你先提交一个 issue，谈谈你想实现的东西。在投入很多精力之前，我们应该先讨论一下是否要这样做，也可以确保我们不重复工作。

编写代码

准备开发环境

开发环境相较于使用环境较为复杂，确保已经安装 Python 3.11+ 和 Poetry，然后通过 Poetry 创建和安装开发环境：

cd Py2exe-GUI
poetry install --with dev --extras "AddOns"

如果你在国内使用 PyPI 源速度较慢，可以考虑取消注释 pyproject.toml 文件中的 [[tool.poetry.source]] 小节，启用国内镜像站。但注意不要将修改后的 poetry.lock 文件提交到 git 中。

还需要通过 pre-commit 安装 git 钩子：

pre-commit install

代码风格

  • 总体来讲，新增和修改的代码应接近原有代码的风格。尽量使代码有良好的可读性。
  • 请使用 Black 格式化代码，确保所有代码风格与项目一致。开发环境中已经安装了 Black，配置使用方法可以参考这篇文章。
  • 请为代码添加充分的类型注解，并能通过 mypy 检查不报错。
  • 请为模块、类、函数/方法、属性等添加 docstring 或注释，确保含义清晰易读。

文档

如果你实现了一些新功能，应考虑在 docs/ 目录下添加相应的文档，或适当修改 README.md 来加以阐述。

测试

由于我的编程水平有限、GUI 程序不易实现自动化测试等原因，Py2exe-GUI 项目暂无测试。如果你想添加一些测试代码，请在整个项目的根目录下创建 tests/ 目录，并将测试代码置于其中。

拉取请求

新建一个指向 muziing/Py2exe-GUI 的 main 分支的拉取请求，我将尽快 review 代码并给出反馈。