Format, test, document and PR

Below are the steps to fork and contribute to this project.

1. Fork and Clone

Create a fork of nornir-validate, download (git clone) a local copy of it and add the original repo as a remote.

git clone git@github.com:<your_github_username>/nornir-validate.git
cd nornir-validate
git remote add upstream https://github.com/sjhloco/nornir-validate.git

2. Python venv and pre-test

Create the Python virtual environment and run all the workflow actions to prove everything is as it should be before starting out.

  • Ruff Formatter is a code formatter for Python that focuses on speed and correctness, similar to black but with a different design philosophy

  • Ruff Linter is an extremely fast Python linter designed as a drop-in replacement for Flake8, isort, pydocstyle, pyupgrade, autoflake, and more

  • MyPy performs static type checking

  • PyTest unit-tests validates core nornir-validate functions and all of the feature templates

uv sync
uv run ruff format --check .
uv run ruff check .
uv run mypy .
uv run pytest -v

Note

This documentation assumes you are using uv for python and package management, if you are using pip use pip install -r requirements.txt and remove uv run from the commands.

3. Branch and make changes

Create a new branch for your work, if you are adding a new validation see the proceeding pages for steps on using the feature_builder.py script to do so.

git checkout -b add_paloalto_panos_show_routing_resource

4. Format, lint, typing and test

The project settings for all of these tools can be found in pyproject.toml, they are used when running the tools locally and when the Github workflow actions are run as part of the PR.

uv run ruff format --check .
uv run ruff check .
uv run mypy .

Before doing the unit testing use the rebuild_test_files.py script to re-build the test files (-ds, -as, -vf), unless a breaking change has been made to a sub-feature you shouldn’t really be seeing any changes to these existing files.

uv run scripts/rebuild_test_files.py
uv run pytest -vv

5. Documentation

For new validations the Read The Docs (RTD) validation table needs updating, if you feel the validation requires more details (unusual to need it) also add an entry in the Validation-specific details section.

To test documentation changes install the docs dependency-group packages (sphinx, sphinx-rtd-theme), build the site locally (in _build) and use the Live Server VScode extension to launch the site and check that the table is formatted correctly in a browser.

uv sync --group docs
cd docs
uv run make html

Once finished cleanup the html build as it is no longer needed, the external RTD site will be automatically rebuilt once the PR has been approved and your branch successfully merged.

uv run clean html

6. Example validations

Working examples of features/sub-features need adding to the example_validation_files, do so in the os_specific xx_validations.yml and all_validations.yml (only needed if is a new sub-feature) files.

7. Commit, push and PR

Stage, commit and push your changes (branch) back to your remote branch.

git add .
git commit -m 'feat(paloalto_panos): Add new template for paloalto_panos show routing resource'
git push origin add_paloalto_panos_show_routing_resource

Before submitting the PR the below MUST always be true:

  • All Ruff, MyPy and unit tests PASS

  • RTD documentation UPDATED

  • New validations ADDED to the examples