|
Packit Service |
a166ed |
Contributing to ansible-freeipa
|
|
Packit Service |
a166ed |
===============================
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
As part of the [FreeIPA] project, ansible-freeipa follows
|
|
Packit Service |
a166ed |
[FreeIPA's Code of Conduct].
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
Reporting bugs or Features
|
|
Packit Service |
a166ed |
--------------------------
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
ansible-freeipa uses [Github issues] for the upstream development, so all RFEs
|
|
Packit Service |
a166ed |
and bug reports should be added there.
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
If you have questions about the usage of ansible-freeipa modules and roles,
|
|
Packit Service |
a166ed |
you should also submit an issue, so that anyone that knows an answer can help.
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
Development
|
|
Packit Service |
a166ed |
-----------
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
Contribute code by submitting a [pull request]. All pull requests should be
|
|
Packit Service |
a166ed |
created against the `master` branch. If your PR fixes an open issue, please,
|
|
Packit Service |
a166ed |
add this information to the commit message, like _"Fix issue #num"_.
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
Every PR will have to pass some automatic checks and be reviewed by another
|
|
Packit Service |
a166ed |
developer(s). Once they are approved, they will be merged.
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
In your commits, use clear messages that include intent, summary of changes,
|
|
Packit Service |
a166ed |
and expected result. Use a template commit message [for modules] and
|
|
Packit Service |
a166ed |
[for roles].
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
Upon review, it is fine to `force push` the changes.
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
**Preparing the development environment**
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
There are some useful tools that will help you develop for ansible-freeipa,
|
|
Packit Service |
a166ed |
and you should install, at least, the modules in `requirements.txt`. You
|
|
Packit Service |
a166ed |
can install the modules with your distribution package manager, or use pip,
|
|
Packit Service |
a166ed |
as in the example:
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
```
|
|
Packit Service |
a166ed |
python3 -m pip install --user -r requirements-dev.txt
|
|
Packit Service |
a166ed |
```
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
We recommend using [pre-commit] so that the basic checks that will be executed
|
|
Packit Service |
a166ed |
for your PR are executed locally, on your commits. To setup the pre-commit
|
|
Packit Service |
a166ed |
hooks, issue the command:
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
```
|
|
Packit Service |
a166ed |
pre-commit install
|
|
Packit Service |
a166ed |
```
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
**Developing new modules**
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
When developing new modules use the script `utils/new_module`. If the module
|
|
Packit Service |
a166ed |
should have `action: member` support, use the flag `-m`.
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
This script will create the basic structure for the module, the required files
|
|
Packit Service |
a166ed |
for tests, playbooks, documentation and source code, all at the appropriate
|
|
Packit Service |
a166ed |
places.
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
**Other helpfull tools**
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
Under directory `utils`, you will find other useful tools, like
|
|
Packit Service |
a166ed |
**lint-check.sh**, which will run the Python and YAML linters on your code,
|
|
Packit Service |
a166ed |
and **ansible-doc-test** which will verify if the documentation added to the
|
|
Packit Service |
a166ed |
roles and modules source code has the right format.
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
Testing
|
|
Packit Service |
a166ed |
-------
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
When testing ansible-freeipa's roles and modules, we aim to check if they
|
|
Packit Service |
a166ed |
do what they intend to do, report the results correctly, and if they are
|
|
Packit Service |
a166ed |
idempotent (although, sometimes the operation performed is not, like when
|
|
Packit Service |
a166ed |
renaming items). To achieve this, we use Ansible playbooks.
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
The Ansible playbooks test can be found under the [tests] directory. They
|
|
Packit Service |
a166ed |
should test the behavior of the module or role, and, if possible, provide
|
|
Packit Service |
a166ed |
test cases for all attributes.
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
There might be some limitation on the testing environment, as some attributes
|
|
Packit Service |
a166ed |
or operations are only available in some circumstances, like specific FreeIPA
|
|
Packit Service |
a166ed |
versions, or some more elaborate scenarios (for example, requiring a
|
|
Packit Service |
a166ed |
configured trust to an AD domain). For these cases, there are some `facts`
|
|
Packit Service |
a166ed |
available that will only enable the tests if the testing environment is
|
|
Packit Service |
a166ed |
enabled.
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
The tests run automatically on every pull request, using Fedora, CentOS 7,
|
|
Packit Service |
a166ed |
and CentOS 8 environments.
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
See the document [Running the tests] and also the section `Preparing the
|
|
Packit Service |
a166ed |
development environment`, to prepare your environment.
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
Documentation
|
|
Packit Service |
a166ed |
-------------
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
We do our best to provide a correct and complete documentation for the modules
|
|
Packit Service |
a166ed |
and roles we provide, but we sometimes miss something that users find it
|
|
Packit Service |
a166ed |
important to be documented.
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
If you think something could be made easier to understand, or found an error
|
|
Packit Service |
a166ed |
or omission in the documentation, fixing it will help other users and make
|
|
Packit Service |
a166ed |
the experience on using the project much better.
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
Also, the [playbooks] can be seen as part of the documentation, as they are
|
|
Packit Service |
a166ed |
examples of commonly performed tasks.
|
|
Packit Service |
a166ed |
|
|
Packit Service |
a166ed |
---
|
|
Packit Service |
a166ed |
[FreeIPA]: https://freeipa.org
|
|
Packit Service |
a166ed |
[FreeIPA's Code of Conduct]: https://github.com/freeipa/freeipa/blob/master/CODE_OF_CONDUCT.md
|
|
Packit Service |
a166ed |
[for modules]: https://github.com/freeipa/ansible-freeipa/pull/357
|
|
Packit Service |
a166ed |
[for roles]: https://github.com/freeipa/ansible-freeipa/pull/430
|
|
Packit Service |
a166ed |
[Github issues]: https://github.com/freeipa/ansible-freeipa/issues
|
|
Packit Service |
a166ed |
[pull request]: https://github.com/freeipa/ansible-freeipa/pulls
|
|
Packit Service |
a166ed |
[playbooks]: playbooks
|
|
Packit Service |
a166ed |
[pre-commit]: https://pre-commit.com
|
|
Packit Service |
a166ed |
[Running the tests]: tests/README.md
|
|
Packit Service |
a166ed |
[tests]: tests/
|