开发环境

准备好贡献代码了吗？以下是如何设置 ansible_rulebook 以进行本地开发

  1. 在 GitHub 上 Fork ansible_rulebook 仓库。

  2. 将你的 Fork 仓库克隆到本地

git clone git@github.com:your_name_here/ansible-rulebook.git

  1. 我们使用一个名为 Drools 的规则引擎，它是用 Java 编写的。在 Python 代码中，我们使用 JPY 直接调用 Drools 的 Java 类。为了使 JPY 正常工作，必须满足以下条件：

    • 已安装 Java 17+

    • 已安装 Maven 3.8.1+（某些 Java 安装包中可能已包含）

    • 如果你想使用与默认版本不同的特定 Java 版本，请相应地设置环境变量 JAVA_HOME

  2. 将你的本地副本安装到虚拟环境（virtualenv）中。假设你已经安装了 virtualenvwrapper，你可以按照以下步骤设置你的 Fork 仓库进行本地开发：

cd ansible_rulebook/
python3.9 -m venv venv
source venv/bin/activate
pip install -e .[development]
pip install -r requirements_dev.txt
ansible-galaxy collection install ansible.eda
npm install commitlint

  1. 创建一个用于本地开发的分支

git checkout -b name-of-your-bugfix-or-feature

现在你可以在本地进行修改了。

  1. 修改完成后，请检查你的更改是否通过了 flake8 和各项测试，包括使用 tox 测试其他 Python 版本

flake8 ansible_rulebook tests
pytest
tox

要获取 flake8、pytest 和 tox，只需将它们 pip 安装到你的虚拟环境中即可。

  1. 提交你的更改并将分支推送到 GitHub：我们遵循 conventionalcommit 提交信息标准。在 pre-commit 阶段，我们将验证提交信息。你必须使用以下命令安装 hook：

pre-commit install --hook-type commit-msg

git add .
git commit -m "fix: title about the bug fix"
git push origin name-of-your-bugfix-or-feature

  1. 通过 GitHub 网站提交 Pull Request。

构建容器镜像

Dockerfile 指向了所需的 Ansible collection，该 collection 提供了源插件。

docker build -t localhost/ansible-rulebook:dev .

Git pre-commit hooks

为了自动运行代码检查器（linters）和代码格式化工具，我们使用 git pre-commit hooks。本项目为 pre-commit 框架提供了配置，以便为你自动设置 hooks。建议使用 pre-commit 以符合 PR 指南。

  1. 在创建开发环境（上述步骤 4）时，会安装 pre-commit 包

  2. 然后生成 git pre-commit hooks

pre-commit install

你可以通过调用以下命令在所有被跟踪的文件上手动运行 pre-commit：

pre-commit run --all-files

提示

运行部分测试

pytest tests.test_ansible_rulebook

运行端到端 (E2E) 测试

pytest -m e2e

运行 Temporal 测试

pytest -m temporal

跳过运行 Temporal 测试

pytest -m "not temporal"

构建

python -m build

注意

软件包版本由 setuptools_scm 自动确定。如果你不是从 git 仓库构建，或者仓库中不包含标签（tags），你可以通过设置 SETUPTOOLS_SCM_PRETEND_VERSION 环境变量来手动指定版本。

发布

在 GitHub 上创建新发布版本，并将软件包上传到 PyPI

twine upload dist/*