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