Developer Setup & Workflow

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• dev/constitution.md
• pyproject.toml
• RELEASING.md
• tasks/docs.py
• dev/guides/adding-an-adapter.md
• dev/guides/testing-an-adapter.md

The infrahub-sync project manages data synchronization between infrastructure systems of record. This page details the environment setup, mandatory verification paths, code quality standards, and automated release gates that developers must follow to build and maintain adapters and core sync features safely.

Sources: dev/constitution.md

Environment Provisioning & Tools

The development environment manages dependencies through uv and structures automation using invoke tasks. The project requires Python 3.10 to 3.13.

Sources: AGENTS.md, pyproject.toml

Initial Setup Procedure

If you are setting up the repository for the first time, perform these steps in order:

1. Configure your local Python interpreter to a supported version between 3.10 and 3.13 using pyenv or your system package manager.
2. Run uv sync to install dependencies and lock synchronization states.
3. Run uv run invoke format to standardize file layouts.
4. Run uv run invoke lint to activate the verification pipeline.

Sources: AGENTS.md

The following flowchart shows the initialization sequence for a fresh environment:

This diagram indicates the execution order required to bring a local sandbox into compliance before editing files.

Sources: AGENTS.md

Code Quality Gates & Pre-Commit Validation

Every code change must satisfy multiple automated linters and type checkers before submission. The test suite isolates network activity by default to ensure local execution remains offline.

Sources: dev/constitution.md, dev/guides/testing-an-adapter.md

Quality Control Pipeline

The verification sequence executes five distinct validation suites when you run uv run invoke lint. The pipeline aborts if any step encounters errors.

Sources: AGENTS.md, dev/constitution.md

Utility	Purpose	Enforcement Rules
ruff	Formatting & Fast Linting	Enforces a maximum line length of 120 characters and structural conventions.
pylint	Deep Static Code Analysis	Validates logical correctness, ignores private method docstring gaps.
yamllint	Configuration Validation	Verifies syntax correctness of adapter mapping files and configurations.
ty	Strict Static Type Checking	Validates type signatures. Overrides in pyproject.toml are prohibited.
rumdl	Markdown & Documentation Linting	Verifies prose and structural correctness of files under docs/.

Sources: AGENTS.md, pyproject.toml, dev/constitution.md

Local CLI Verification

Before creating a commit, you must verify the CLI tool manually against the sanitized template configurations. Run these safe, non-mutating validation checks:

uv run infrahub-sync --help
uv run infrahub-sync list --directory examples/
uv run infrahub-sync generate --name from-netbox --directory examples/

Sources: AGENTS.md

Testing Standards & Mocking Practices

The project separates execution environments into atomic, offline unit tests and opt-in integration tests.

Sources: dev/constitution.md, dev/guides/testing-an-adapter.md

Mocking Third-Party SDKs

Adapters import upstream software development kits (SDKs) as optional dependencies. You must intercept external communication at the client level using unittest.mock.MagicMock.

Sources: dev/guidelines/writing-an-adapter.md, dev/guides/testing-an-adapter.md

import pytest
# Guard module collection if the optional dependency is missing
pytest.importorskip("pynetbox")

from unittest.mock import MagicMock
from infrahub_sync.adapters.mysystem import MysystemAdapter

def test_loader_maps_fields():
    # Instantiate the target adapter using dummy configuration structures
    adapter = MysystemAdapter(target="source", adapter=MagicMock(), config=MagicMock())
    adapter.client = MagicMock()
    
    # Configure mock responses matching expected API shapes
    adapter.client.get.return_value = [{"name": "rtr1", "device_type": "qfx"}]
    assert adapter.client.get() == [{"name": "rtr1", "device_type": "qfx"}]

Sources: dev/guides/testing-an-adapter.md

Execution Commands

Run the test suite using standard pytest invocations. To activate live network scenarios, you must explicitly pass the integration flag:

# Run the fast, network-isolated unit tests
uv run pytest -q

# Run live target sync verification (requires target services)
uv run pytest -m integration

Sources: AGENTS.md, pyproject.toml, dev/guides/testing-an-adapter.md

Documentation Maintenance

When user-facing alterations, new CLI flags, or new sync configuration schemas are introduced, you must update the corresponding document paths within the same iteration.

Sources: AGENTS.md, dev/constitution.md

Documentation Management Commands

You can build, update, and validate documentation files via invoke namespaces:

# Automatically regenerate Typer CLI reference documentation
uv run invoke docs.generate

# Validate Markdown formatting and structure via rumdl
uv run invoke docs.rumdl

# Test production Docusaurus builds locally
uv run invoke docs.docusaurus

Sources: AGENTS.md, tasks/docs.py

The document generation process passes internal data models through typer-cli to output an updated reference page:

Pull Request Guidelines & Automated Release Gate

Versions and change documents are managed systematically by automation. Manual changes to CHANGELOG.md or the version fields inside pyproject.toml are prohibited.

Sources: AGENTS.md, RELEASING.md

News Fragments

Every pull request that targets the main branch must introduce a single, independent news fragment file inside the changelog/ directory.

• Filename convention: <id>.<type>.md (e.g., 123.fixed.md).
• If no issue ID exists, use a plus sign prefix: +short-slug.housekeeping.md.
• Permitted types: security, removed, deprecated, added, changed, fixed, housekeeping.

Sources: AGENTS.md, pyproject.toml

Version Bump Calibration

Automated tracking matches pull request labels to determine the next release increment.

Pull Request Label	Version Increment	Typical Applications
changes/major, type/breaking-change	Major (1.0.0 $\rightarrow$ 2.0.0)	Incompatible API modifications or structural shifts.
changes/minor, type/feature, type/refactoring	Minor (1.0.0 $\rightarrow$ 1.1.0)	Non-breaking functional additions.
changes/patch, type/bug, type/housekeeping	Patch (1.0.0 $\rightarrow$ 1.0.1)	Internal maintenance, documentation fixes, bug resolution.

Sources: RELEASING.md

Automated Release Promotion

To execute a project release, follow this sequence:

This structural architecture guarantees that every PyPI artifact aligns perfectly with consumed changelog records and reviewed branch history.

Sources: RELEASING.md

Conclusion

Following these steps provides a safe workflow for developing infrahub-sync. The separation of read-only logic, strict local quality gates, and automated release steps protect data integrity across all synchronized infrastructure architectures.

Sources: dev/constitution.md