diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000000000000000000000000000000000..c0222af4a1ed1a26dd50c1c94d57ed936a153baa --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,121 @@ +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/