Feature Specification & Planning
Relevant source files
The following files were used as context for generating this wiki page:
Feature Specification and Planning within the infrahub-ansible project provides a structured framework for defining, designing, and executing technical changes. This process utilizes a "spec-kit" workflow that generates retroactive and proactive documentation, including functional specifications, implementation plans, and granular task lists. The system ensures that all features align with the project's Core Principles and follow established architectural patterns.
The planning process is categorized into distinct phases—Setup, Foundation, User Stories, and Verification—ensuring that work is independently testable and verifiable. This structure supports complex optimizations, such as the Dynamic Inventory Fetch Performance, and process overhauls, such as the Towncrier-based release workflow.
Sources: specs/001-inventory-fetch-performance/plan.md:1-20, specs/002-towncrier-release-process/spec.md:1-15
Specification and Planning Workflow
The project follows a rigorous workflow for specifying and planning features. This lifecycle transitions from high-level user scenarios to detailed implementation tasks.
Documentation Hierarchy
| Artifact | Purpose | Derived From |
|---|---|---|
| Specification (spec.md) | Defines functional requirements, success criteria, and user scenarios. | User requirements / Feature description |
| Implementation Plan (plan.md) | Maps requirements to technical architecture, project structure, and constitution gates. | spec.md |
| Task List (tasks.md) | Breaks down the implementation into granular, sequential, and parallel steps. | plan.md and spec.md |
Sources: specs/001-inventory-fetch-performance/plan.md:55-66, specs/002-towncrier-release-process/tasks.md:1-15
Feature Lifecycle Diagram
The following diagram illustrates the progression from feature conception to verification.
The flow shows how requirements are gated by a Constitution Check before being broken into executable tasks.
Sources: specs/001-inventory-fetch-performance/tasks.md:20-50, specs/002-towncrier-release-process/plan.md:35-50
Core Principles & Governance Gates
Every feature must pass a "Constitution Check" during the planning phase. This ensures compliance with the opsmill.infrahub Ansible Collection Constitution.
Constitutional Principles
- Ansible Collection Standards: Ensures correct headers, imports (e.g.,
from __future__ import absolute_import), and metaclass boilerplate (__metaclass__ = type). - Two Plugin Patterns: Restricts plugins to either the Module-utils pattern (idempotent CRUD) or the Action plugin pattern (controller-side API calls).
- Idempotency and State Management: Mandates a fetch-compare-act cycle for modules managing Infrahub objects.
- SDK Abstraction Layer: Requires all API access to be mediated through
InfrahubclientWrapper. rawInfrahubClientSyncuse is prohibited. - Test Coverage: Enforces three tiers of testing: Sanity, Unit, and Integration.
Sources: dev/constitution.md:15-80, specs/001-inventory-fetch-performance/plan.md:38-52
Ask First Gates
Certain changes require explicit approval as defined in the project governance:
- Adding new dependencies to
pyproject.toml. - Modifying CI workflows in
.github/workflows/. - Changing the
INFRAHUB_ARG_SPEC. - Modifying the core shared utility
plugins/module_utils/infrahub_utils.py.
Sources: specs/002-towncrier-release-process/spec.md:90-105
Implementation Planning (Phase-based)
Implementation is organized into logical phases to manage complexity and ensure that foundational work precedes feature-specific logic.
Standard Implementation Phases
- Phase 1: Setup: Creation of boilerplate, shared infrastructure, and SDK-free modules for testing.
- Phase 2: Foundational: Modifications that every subsequent user story depends on (e.g., core wrapper changes).
- Phase 3-N: User Stories: Independent implementation of specific feature goals, each accompanied by its own tests.
- Phase Final: Verification & Polish: Documentation updates, final linting, and repo hygiene.
Sources: specs/001-inventory-fetch-performance/tasks.md:40-150
release-prepare Planning Sequence
For the Towncrier-based release process, the sequence involves specific CI and packaging tasks.
The diagram shows the release planning flow where manual review of an auto-generated Release PR is a critical gate.
Sources: specs/002-towncrier-release-process/spec.md:25-50, specs/002-towncrier-release-process/tasks.md:55-100
Performance & Scalability Planning
Features involving performance, such as dynamic inventory fetching, define specific measurable outcomes.
Performance Goals (Example: Inventory Fetch)
- FR-001: Query count MUST be determined by node types and pages, NOT host count.
- FR-005: Related nodes MUST be retrieved in batches grouped by type.
- SC-001: Target reduction in build time (e.g., 100s to <10s for ~650 hosts).
Sources: specs/001-inventory-fetch-performance/spec.md:85-95, specs/001-inventory-fetch-performance/plan.md:25-35
Performance Measurement Table
| Metric | Previous Behaviour | Optimized Target/Result |
|---|---|---|
| Wall-clock (652 hosts) | 102.71s | 3.23s |
| Request Count | 700 requests | 15 requests |
| Data Transferred | 3758 KB | 1555 KB |
Sources: specs/001-inventory-fetch-performance/plan.md:30-34
Summary
Feature Specification & Planning in infrahub-ansible serves as the blueprint for maintaining collection quality and performance. By enforcing a Constitution Check and a phased task breakdown, the project ensures that new features like optimized inventory fetching and automated release processes are robust, auditable, and compliant with Ansible standards. The use of retroactive specifications (spec.md) and implementation plans (plan.md) provides a permanent record of design decisions and technical constraints.