Skip to content

Contributing

Contributions are welcome - modules for uncovered NetOrca resources, examples, documentation and bug reports alike. Issues and merge requests live on GitLab. For anything non-trivial, open an issue first so the approach can be agreed before you invest in code.

Development environment

$ git clone https://gitlab.com/netorca_public/netorca_ansible.git && cd netorca_ansible
$ uv venv && source .venv/bin/activate
$ uv pip install -r test-requirements.txt -r docs-requirements.txt
$ pre-commit install
$ make help          # the full list of dev entrypoints

pre-commit runs ruff (lint + format) and basic hygiene hooks on every commit. Note that a hook that modifies a file fails the commit on purpose - re-stage and commit again.

Repository layout

Path What it is
plugins/module_utils/netorca.py the shared base layer every module builds on: connection args + env fallbacks, SDK client construction, exception→failure mapping, pagination, filter serialisation, the raw escape hatch for SDK gaps
plugins/modules/ one file per module; *_info read, the rest write
plugins/doc_fragments/netorca.py shared documentation fragments (connection, context, info options)
tests/unit/ pytest suite, SDK fully mocked (details)
tests/integration/ live playbooks, credential-gated (details)
docs/ this site; docs/modules/ is generated - do not edit
examples/ runnable example playbooks, indexed in Examples
scripts/ docs generator, collection-path shim, integration runner, release script
changelogs/fragments/ changelog entries for unreleased changes

Design rules the modules follow

These are the conventions reviewers will hold a new module to:

  1. One module, one resource, one concern. Reads go in netorca_<resource>_info; writes are a state-based netorca_<resource>; non-idempotent verbs get a netorca_<resource>_<verb> action module.
  2. Explicit, validated filters. Every filter the platform supports for the endpoint is a real module parameter with types and choices - never an opaque dict. Platform enums are constants in module_utils/netorca.py.
  3. Everything flows through the base layer. SDK calls go through module.call() (exception mapping), listings through module.collect() (pagination + limit), filters through module.build_filters(), results out through module.exit_resources() / module.exit_write(). If the SDK cannot express a call, use the raw layer (module.raw_list() / module.raw_request()) and leave a comment naming the SDK gap.
  4. Real check mode and diff. Write modules fetch, compare, and only then mutate; in check mode they exit with the projected result. changed must mean something.
  5. Info modules return empty, not errors, when nothing matches - including ID lookups.
  6. Docs are not optional. Full DOCUMENTATION/EXAMPLES/RETURN with the shared fragments, attributes, seealso, and FQCN (netautomate.netorca.<module>) in every example. GPLv3 header in every plugin file (validate-modules enforces it).

Adding a module - checklist

  1. Module file under plugins/modules/, following the design rules above. The four existing modules are the reference implementations.
  2. Unit tests: a new row-set in the table-driven info suite, or a dedicated file for write logic.
  3. Regenerate the module reference: make docs - commit the new page under docs/modules/.
  4. A changelog fragment (next section).
  5. An example playbook under examples/ if the module enables a new workflow, plus a scenario doc under docs/scenarios/ when it completes one.
  6. All green locally: make lint sanity units docs-check.

Changelog fragments

Every user-visible change ships a fragment in changelogs/fragments/ (any filename, .yml):

# changelogs/fragments/my-change.yml
minor_changes:
  - netorca_service_item_info - add the C(change_state) filter.

Sections: release_summary, breaking_changes, major_changes, minor_changes, bugfixes, deprecated_features, removed_features, security_fixes, trivial (not rendered). The fragments are compiled into CHANGELOG.rst at release time by antsibull-changelog - never edit CHANGELOG.rst directly.

Merge requests

  • Branch from main, MR back to main. Reference the issue (Closes #NN) in the description.
  • The whole pipeline must be green; the manual integration job is optional but appreciated for changes touching request/response handling.
  • Keep MRs scoped - one module family or one concern per MR reviews fastest.