Contributing¶

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions¶

Report Bugs¶

Report bugs at https://github.com/ansible/ansible-rulebook/issues.

If you are reporting a bug, please include:

Your operating system name and version.
Any details about your local setup that might be helpful in troubleshooting.
Detailed steps to reproduce the bug.

Fix Bugs¶

Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.

Implement Features¶

Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.

Write Documentation¶

ansible-rulebook could always use more documentation, whether as part of the official ansible-rulebook docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback¶

The best way to send feedback is to file an issue at https://github.com/ansible/ansible-rulebook/issues.

If you are proposing a feature:

Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!¶

Ready to contribute? Here’s how to set up ansible_rulebook for local development.

Fork the ansible_rulebook repo on GitHub.

Clone your fork locally:

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

We use a rules engine called Drools which is written in Java. From our python code we directly call the Drools Java classes using JPY. JPY needs Java to be installed on the machine. There are wheel distributions for JPY but they might not match your hardware so you would have to compile the JPY from source to get the package and shared object appropriate for your machine. To compile from Source you would need to set the following env var export PIP_NO_BINARY=jpy
- Java 11+ installed
- Environment variable JAVA_HOME set accordingly
- Maven 3.8.1+ installed, might come bundled in some Java installs

Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:

$ cd ansible_rulebook/
$ python3.9 -m venv venv
$ source venv/bin/activate
$ pip install -e .
$ pip install -r requirements_dev.txt
$ ansible-galaxy collection install ansible.eda

Create a branch for local development:
```
$ git checkout -b name-of-your-bugfix-or-feature
```
Now you can make your changes locally.
When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:
```
$ flake8 ansible_rulebook tests
$ pytest
$ tox
```
To get flake8 and tox, just pip install them into your virtualenv.

Commit your changes and push your branch to GitHub:

$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

Submit a pull request through the GitHub website.

Building the container image¶

The dockerfile points to the required collection of ansible which provides source plugins.

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

Git pre-commit hooks (optional)¶

To automatically run linters and code formatter you may use git pre-commit hooks. This project provides a configuration for pre-commit framework to automatically setup hooks for you.

First install the pre-commit tool:

Into your virtual environment:
(venv) $ pip install pre-commit
Into your user directory:
$ pip install --user pre-commit
Via pipx tool:
$ pipx install pre-commit

Then generate git pre-commit hooks:

$ pre-commit install

You may run pre-commit manually on all tracked files by calling:

$ pre-commit run --all-files

Pull Request Guidelines¶

Before you submit a pull request, check that it meets these guidelines:

The pull request should include tests.
If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
The pull request should work for Python 3.9

Tips¶

To run a subset of tests:

$ pytest tests.test_ansible_rulebook

Deploying¶

A reminder for the maintainers on how to deploy. Make sure all your changes are committed (including an entry in HISTORY.rst). Then run:

$ bump2version patch # possible: major / minor / patch
$ git push
$ git push --tags

Releasing¶