From 52a4bdcf4c7fc197af653ac8c572546aa3097da7 Mon Sep 17 00:00:00 2001 From: Rafael Guterres Jeffman <rjeffman@redhat.com> Date: Fri, 30 Oct 2020 17:28:08 -0300 Subject: [PATCH] Add CONTRIBUTING.md file. 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. --- CONTRIBUTING.md | 121 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..c0222af4 --- /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/ -- GitLab