如何贡献¶
欢迎贡献!还不熟悉代码库?没问题!有很多方法可以为开源项目做出贡献:报告错误、帮助文档、传播信息,当然还有添加新功能和补丁。
支持性问题¶
请不要为此使用问题跟踪程序。请使用以下资源之一解答有关您自己代码的问题:
问 Stack Overflow . 首先使用谷歌搜索:
site:stackoverflow.com eve {{search term, exception message, etc.}}
这个 mailing list 旨在为寻求帮助或请求反馈的开发人员/贡献者和API维护人员提供低流量资源。
IRC信道
#python-eve
关于弗雷诺德。
报告问题¶
描述你期望发生的事情。
如果可能,包括 minimal, complete, and verifiable example 帮助我们找出问题所在。这也有助于检查问题是否与您自己的代码无关。
描述实际发生的事情。如果出现异常,请包括完整的回溯。
列出您的python和eve版本。如果可能,请检查存储库中是否已修复此问题。
正在提交修补程序¶
包括测试,如果你的补丁应该解决一个bug,并清楚地解释在什么情况下会发生这个bug。确保测试在没有补丁的情况下失败。
启用并安装 pre-commit 以确保遵循样式指南和编解码器检查。CI将拒绝不符合准则的变更。
首次设置¶
下载并安装 latest version of git .
-
git config --global user.name 'your name' git config --global user.email 'your email'
确保你有一个 GitHub account .
通过单击 Fork 按钮。
Clone 您在本地的Github复刻:
git clone https://github.com/{username}/eve cd eve
将主存储库添加为远程,稍后更新:
git remote add pyeve https://github.com/pyeve/eve git fetch pyeve
创建virtualenv::
python3 -m venv env . env/bin/activate # or "env\Scripts\activate" on Windows
在具有开发依赖项的可编辑模式下安装EVE::
pip install -e ".[dev]"
安装 pre-commit 然后激活它的钩子。预提交是管理和维护多语言预提交挂钩的框架。EVE使用预提交来确保代码样式和代码格式相同:
$ pip install --user pre-commit $ pre-commit install
之后,每次提交时都会运行预提交。
起始编码¶
创建一个分支以标识您要处理的问题(例如
fix_for_#1280
)使用您最喜欢的编辑器进行更改, committing as you go .
跟随 PEP8 .
包括包含您所做的任何代码更改的测试。确保测试在没有补丁的情况下失败。 Run the tests. .
推动你对Github的承诺 create a pull request .
庆贺 🎉
运行测试¶
您的系统中应该有可用的Python3.7+。现在运行测试就像发出以下命令一样简单::
$ tox -e linting,py37,py38
该命令将通过“tox”工具对Python3.7和3.8运行测试,并执行“lint”编码风格的检查。
可以将不同的选项传递给 tox
。例如,要在Python3.10上运行测试并将选项传递给pytest(例如,失败时输入pdb)到pytest,您可以执行以下操作:
$ tox -e py310 -- --pdb
或者只在Python3.6上的特定测试模块中运行测试:
$ tox -e py310 -- -k TestGet
当您提交拉取请求时,CI将运行完整的套件。完整的测试套件需要很长时间才能运行,因为它测试了Python和依赖项的多种组合。您需要安装Python3.7、3.8、3.9、3.10和PyPy才能运行所有环境。然后运行::
tox
请注意,您需要在本地主机上运行一个活动的MongoDB实例才能运行测试。使用在 test_settings.py 管理数据库中的文件(如果您不想提交管理员凭据,但仍然修改了文件,这对于tox来说是必需的),那么预提交过程是不可原谅的。如果您想运行一个本地MongoDB实例和一个SSH隧道到一个远程实例,如果可以的话,让本地使用默认端口,让远程使用其他端口。如果不能,修复不能正常运行的测试可能比一次连接一个远程和本地实例更麻烦。此外,请注意,为了执行 速率限制 你需要跑步的测试 Redis 服务器。如果不满足这两个条件中的任何一个,将静默跳过速率限制测试。
构建文档¶
在中生成文档 docs
使用sphinx的目录:
cd docs
make html
正常开放 _build/html/index.html
在浏览器中查看文档。
阅读更多有关 Sphinx .
制作目标¶
EVE提供了 Makefile
有各种快捷方式。它们将确保安装所有依赖项。
make test
runs the basic test suite withpytest
make test-all
runs the full test suite withtox
make docs
构建HTML文档make check
对包执行一些检查make install-dev
在所有开发依赖项的可编辑模式下安装EVE。
第一次投稿人?¶
没关系。我们都去过那里。见下一章。
不知道从哪里开始?¶
代码库中通常会散布一些TODO注释,可以检查它们,看看您是否有想法,或者可以帮助它们。另外,检查 open issues 万一有什么事引起你的兴趣。文件呢?我不擅长英语,所以如果你能流利地使用它(或者注意到任何拼写错误和/或错误),为什么不帮忙呢?在任何情况下,除了Github help 页数,你可能想检查这个很好 Effective Guide to Pull Requests