CONTRIBUTING.md

Developing Schemas

You are welcome to contribute to the schemas for Ansible and Molecule!

Setting up the project for development

We are using task as a build tool and if you want to see the list of tasks available without running them run task -l or look inside Taskfile.yml.

Extending the schemas

The schemas are in the directory f/. You can modify most of them directly, the only exception being ansible-playbook.json and ansible-task.json which are automatically generated from ansible.json file. So, if you want to modify one of these, you will only need to modify the source file and run task command to regenerate the other two files and run the test suite.

When making a schema change, you are also expected to add at least one test file inside either tests/ or negative_tests/ folders. You do not need to write any code for these as our test suits transforms each file into a test.

The negative tests are expected to fail and they also have a markdown file that describes the expected error message. These .md files are automatically generated by task test but you will need to include the modified ones in your pull requests. If you fail to include the modified .md files, the CI will fail and display a git diff between the tracked version of them and the effective outcome.

The expectation is that git command would not report dirty before or after running the task command. If it passes, you are ready to submit a pull request.

To better understand how an atomic pull request should look, take a look at #290 pull request. You will see that it includes:

• A schema change to ansible.json file
• The regenerated ansible-playbook.json and ansible-task.json files
• A modified negative_test/roles/meta_invalid_role_namespace/meta/main.yml.md file, which is the result of schema change.
• A new test/playbooks/tasks/templated_integers.yml file, which is effectively testing that this schema change is valid. This file would have failed the test unless the schema change was made. That is important for preventing future regressions when the schema is updated.

Updating dependencies

To update the test dependencies run task deps and if all tests are passing make a pull request to update them.

Submitting Pull Requests

Fixes and features for schemas will go through the Github pull request process. Submit your pull request (PR) against the main branch.

Here are a few things you can do to help get your pull request accepted faster:

• Run task and check that it returns without reporting any errors.
• Write good commit messages. See How to write a Git commit message.

Reporting Issues

We welcome your feedback and encourage you to file an issue when you run into a problem.