Snippets Groups Projects

4 years ago

Add CONTRIBUTING.md file. · 52a4bdcf

Rafael Guterres Jeffman authored 4 years ago

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.

52a4bdcf

Add CONTRIBUTING.md file.

Rafael Guterres Jeffman authored 4 years ago

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.

After you've reviewed these contribution guidelines, you'll be all set to contribute to this project.

CONTRIBUTING.md 4.29 KiB

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.