Git Workflow

Relevant source files

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

• dev/guidelines/git-workflow.md
• AGENTS.md
• tasks.py
• pyproject.toml
• CHANGELOG.md
• dev/guidelines/python.md
• dev/adr/0001-adopt-canonical-agentic-structure.md

The Git workflow defines how contributions flow into the nornir-infrahub repository. It ensures code quality through mandatory local gates, automated CI checks, and structured changelog management. This workflow complements the core contributor boundaries established in the project guidelines.

Sources: dev/guidelines/git-workflow.md:1-5, AGENTS.md:1-5

Branching Model

The project utilizes a simplified branching strategy centered around a single protected branch.

• stable branch: This is the default and protected branch. All development work targets this branch.
• Feature Branches: You must create a feature branch for any work and open a Pull Request (PR) against stable.
• Stale Refs: The main and develop branches are stale and must be ignored. origin/HEAD resolves to origin/stable.

Sources: dev/guidelines/git-workflow.md:7-12

Local Development Lifecycle

Before pushing code, you must execute a specific sequence of quality gates. These gates ensure that all Python and Markdown files adhere to the project's formatting and linting standards.

Pre-commit Sequence

1. Format Code: Use invoke format to run ruff format, ruff check --fix, and rumdl fmt.
2. Lint Code: Use invoke lint to execute all linters in order (yamllint, ruff, pylint, ty, and rumdl).
3. Run Tests: Execute unit tests using pytest. Integration tests are excluded by default.

Sources: dev/guidelines/git-workflow.md:14-25, tasks.py:20-68, AGENTS.md:30-45

Linting Commands Summary

Task	Command	Description
Full Lint	invoke lint	Runs all linters in sequence.
Format	invoke format	Formats Python (ruff) and Markdown (rumdl).
Ruff	invoke lint-ruff	Python linting and code style.
Pylint	invoke lint-pylint	Advanced Python static analysis.
Ty	invoke lint-ty	Type checking for nornir_infrahub.
Yaml	invoke lint-yaml	Validates YAML files.
Markdown	invoke lint-markdown	Checks Markdown structure and style.

Sources: tasks.py:20-68, AGENTS.md:34-42

Commit and Changelog Standards

The project follows specific conventions for documenting changes to ensure a clear history for users and automated tools.

Commit Messages

While there is no strictly enforced regex, messages should follow conventional-commit prefixes (e.g., fix:, docs:, chore:). Merged PRs carry the PR number as a suffix (e.g., (#29)).

Sources: dev/guidelines/git-workflow.md:38-44

Towncrier Fragments

Changes are recorded using towncrier. You must never edit the released sections of CHANGELOG.md by hand. Instead, add a fragment file under changelog/ named <issue-or-pr>.<type>.md.

Fragment Types defined in pyproject.toml:

• security
• removed
• deprecated
• added
• changed
• fixed
• housekeeping

Sources: dev/guidelines/git-workflow.md:46-60, pyproject.toml:236-258

Pull Request and CI Process

Pull Requests are the only mechanism for merging code into the stable branch. All PRs trigger the CI workflow (.github/workflows/ci.yml).

CI Gates

The CI runs specific jobs based on the files changed:

• python-lint: Executes ruff, ty, and pylint (Python 3.14).
• python-tests: Runs pytest across Python versions 3.10 through 3.14.
• yaml-lint: Executes yamllint.
• markdown-lint: Executes rumdl.
• documentation: Validates documentation style with Vale and builds the Docusaurus site.

Sources: dev/guidelines/git-workflow.md:70-83, pyproject.toml:9-16

Merge Requirements

• All CI gates must be green.
• No lint or type gates should be disabled to pass CI.
• Sensitive changes (Plugin API, inventory mapping semantics, SDK upgrades) require explicit sign-off.

Sources: dev/guidelines/git-workflow.md:27-30, dev/guidelines/git-workflow.md:85-91

Dependency Management

Dependency changes are strictly controlled. Adding, removing, or bumping a dependency in pyproject.toml requires justification and prior approval.

• Pinning: Every dependency must be pinned with both a lower and an upper bound (e.g., infrahub-sdk>=1.20.1,<2).
• Management Tool: uv is used for dependency and virtual environment management.

Sources: dev/guidelines/git-workflow.md:93-96, pyproject.toml:17-23, AGENTS.md:104-106

The nornir-infrahub Git workflow emphasizes strict adherence to local quality gates and structured documentation via towncrier. By targeting the stable branch and requiring comprehensive CI validation, the project maintains a high standard of reliability for its inventory and task plugins.

Sources: dev/guidelines/git-workflow.md:98-102, CHANGELOG.md:1-10