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.

ipadnsforwardzone: Fix documentation for `forwarders` usage.

Add pre-commit configuration for linters.

ipadnszone: Fix modification o SOA serial with other attributes.

ipadnsrecord: fix record update when multiple records exist.

There was a failure when NAPTR or DLV records where updated,
if the record name had multiple entries. This patch fixes this
behavior, by using the requested record, not the retrieved one.

Tests have been updated to test for this issue on

    tests/dnsrecord/test_dnsrecord.yml

Due to an issue with FreeIPA, when modifying the SOA serial attribute
along with other attributes, the value is ignored. In order to have
the value provided, the attribute is set is a later call to dnszone-mod
allowing it to retain the desired value.

Ref: https://pagure.io/freeipa/issue/8489

ipadnsrecord: fix record modification behavior.

Examples of dnsforwarzone were using a single string rather than a
dict of values to set attribute `forwarders`. Both source code and
README examples were fixed.

Fix issue #446

Fix lookup for certicates in tests

The file lookup is by default setting `rstrip=True` which could lead
into a stripped new line. This is not happening always but resulted in
failed tests sometimes with certificates pasted to the b64encode filter.

For calls of lookup in the certificae tests `rstrip=False` has been
added to make sure that this is not happening any more. Not in
test_dnsrecord as lookup(..., rstrip=False) is adding a new line if
there was not a new line and this is an issue for dnsrecord. The user
and host tests have also been simplified to create the base64 encoded
file in the beginning and use this file then later on in the tests
without the need to use the b64encode filter.

Ref: https://github.com/ansible/ansible/issues/57521#issuecomment-502238000

ipaserver: copy_external_cert should use basename on server only

README.md: Add missing roles and modules

This patch adds another lever of linter checking for ansible-freeipa
by enabling linters to run on the developer machine, before pushing
changes to be evaluated on the CI, allowing code fixes without
wating for CI to run the linters on the repository.

To enable pre-commit hooks, `pre-commit` is used, and was added to
requirements-dev.txt, and can be installed with pip
(`pip install -r requirements-dev.txt`). Once installed, on every
commit, YAML and python files on the commit will be evaluated.

If one needs to bypass the pre-commit linters, `git commit` can be
issued with `--no-verify`.

The linters will not be removed from the CI, as a commit can be
performed without running the checks.

This change fixes retrieval of CERT values from server data, that
was failing due to wrong attribute name.

When modifying a record, depending on how the playbook tasks were
arranged, it was possible to end with more records than expected.

This behavior was fixed by modifying the way records are searched
when a modification is requested. This change also allows less calls
find_dnsrecord.

Tests were modified to reflect the changes, and a new test playbook
was added:

    tests/dnsrecord/test_dnsrecord_modify_record.yml

Currently the certifaictes are copied ot the server with the complete
path that is provided within the playbook. This could result in
unexpected file placements. Certificates should be placed in the /root
folder for the deployment.

Fixes #405 (copy_external_cert does not handle pathed items)

Information about the backup role and also the config, delegation, dns
config, location, permission, priviledge and self service modules have been
missing in the main README file.

Remove inline certificates from module test playbooks.

Add action to verify Ansible documentation on each commit or PR.

This change make ansible-doc-test skip processing a role if it does
not contain a `library` directory.

This change add support for running ansible-doc-test on every
commit or PR, ensuring that roles and modules are able to produce
correct documentation with ansible-doc.

Support namespace and name in utils/build-galaxy-release.sh as args

The currently used namespace and collection name are hard coded in
utils/build-galaxy-release.sh. They can now be defined as args 1 and 2
and default to freeipa and ansible_freeipa..

Fix ipapermission documentation issue with ansible-doc.

Add KRA requirement to test documentation.

Add FreeIPA version check to module_utils.ansible_freeipa_module.

FreeIPA 4.8.7 has introduced bind type 'self' as a valid value, and
this PR adds checks so the module fails early if the value is used
with an unsupported version.

Tests and documentation have been updated to reflect the changes.

Some attribute values are only accepted for specific FreeIPA versions,
for example `self` for permission's `bindtype`. Although there are
options to check for command and parameter availability, there is no
check for verifying if a value should be accepted.

This patch add a function to evaluate the target FreeIPA host version,
by comparing a giver version to the current installed one.

The version evaluation uses Python packaging's version comparision,
which is compatible with PEP 440, if available. If not available, it
falls back to a string split, that will work for the most common cases,
but might fail for versions including strings with `rc` or `dev`, for
example.

Bypass Ansible filtering on data returned by the module.

Fix utils/changelog for merge commits without subject

Due to Ansible filtering out values in the output that might be match
values in sensible attributes that have `no_log` set, if a module need
to return data to the controller, it cannot rely on
`ansible_module.exit_json` if there is a chance that a partial match
may occur.

See: https://github.com/ansible/ansible/issues/71789

The change provided here uses the same implementation that is used on
Ansible's `AnsibleModule.exit_json`, without the data filtering layer,
so every attribute with be printed and, therefore, logged by Ansible.

This is needed for the Vault module, as we need to return values that
are explicit requested by the user and that might, at least partially,
match the values in attributes with `no_log` set.

Tests that reproduced the issue, and show it was fixed were provided
for all Vault types.

Add support for adding external members to ipagroup.

build-galaxy-release: Galaxyfy READMEs, module EXAMPLES and tests

Up to now the snippets in the README files, the EXAMPLES in the modules
and also the tests playbooks have not been adapted while building the
collection.

These are the invoved python files:

    utils/galaxyfy-README.py
    utils/galaxyfy-module-EXAMPLES.py
    utils/galaxyfy-playbook.py
    utils/galaxyfy.py

utils/galaxyfy.py provides the function galaxyfy_playbook, which has been
extended and is used in galaxyfy-playbook.py, galaxyfy-README.py and
galaxyfy-module-EXAMPLES.py.

There is curently a merge commit without a subject, which leads into a
traceback in the changelog script.

The merge information provides the commit hash, which is now used to get
the subject later on using the generated commits hash.

New backup role

There is a new backup role in the roles folder:

    roles/ipabackup

This role allows to backup an IPA server, to copy a backup from the
server to the controller, to copy all backups from the server to the
controller, to remove a backup from the server, to remove all backups
from the server, to restore an IPA server locally and from the controller
and also to copy a backup from the controller to the server.

Here is the documentation for the role:

    roles/ipabackup/README.md

New example playbooks have been added:

    playbooks/backup-server.yml
    playbooks/backup-server-to-controller.yml
    playbooks/copy-backup-from-server.yml
    playbooks/copy-all-backups-from-server.yml
    playbooks/remove-backup-from-server.yml
    playbooks/remove-all-backups-from-server.yml
    playbooks/copy-backup-to-server.yml
    playbooks/restore-server-from-controller.yml
    playbooks/restore-server.yml

The test README only required than DNS support was enabled, but,
currently, testing support requires KRA for ipavault.