docs(dev): author dev/ guides, guidelines, knowledge, and seed ADRs - #358
Merged
Conversation
Add a dev/constitution.md pointer; a markdown guideline and a module-docstrings guideline; guides for adding a doc fragment and debugging ansible-test sanity failures; a knowledge deep-dive on the inventory + lookup plugins; and three seed ADRs (two-plugin-patterns, sdk-abstraction-wrapper, sync-only-sdk). Rewrite dev/README.md to the peer Quick-Navigation table format. Aligns dev/ with the styrmin / infrahub-mcp conventions. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Deploying infrahub-ansible with
|
| Latest commit: |
cce3b33
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://73c77e32.infrahub-ansible.pages.dev |
| Branch Preview URL: | https://chore-dev-docs-alignment.infrahub-ansible.pages.dev |
BeArchiTek
added
ci/skip-changelog
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
2 issues found across 10 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="dev/guides/adding-a-doc-fragment.md">
<violation number="1" location="dev/guides/adding-a-doc-fragment.md:49">
P2: Step 2's FQCN example omits the filename (`fragments`). All fragments live in `plugins/doc_fragments/fragments.py` as class attributes, so the collection-qualified reference must include the file name before the attribute.</violation>
</file>
<file name="dev/adr/0003-sync-only-sdk.md">
<violation number="1" location="dev/adr/0003-sync-only-sdk.md:23">
P2: Dependency version range in ADR (`>=1.5, <2.0`) does not match the actual project requirement (`>=1.19.0,<2.0`). This will mislead contributors about compatibility.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
Round out the dev/ reference: a releasing-the-collection guide, a processors-and-arg-spec knowledge doc, and ADRs 0004 (docker-based testing) + 0005 (doc-generation pipeline). Fix stale .markdownlint.yml references to .markdownlint.yaml and refresh the dev/README.md nav. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
BeArchiTek
force-pushed
the
chore/dev-docs-alignment
branch
from
June 29, 2026 22:46
f4e8516 to
e9854d9
Compare
…titution.md The constitution wiring is flipped to match the peer repos (infrahub, infrahub-mcp, styrmin): dev/constitution.md holds the real body and .specify/memory/constitution.md symlinks to it — both provided by #356. Remove the now-redundant pointer stub here (avoids a merge conflict with #356's real dev/constitution.md) and fix the dev/README description. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
2 issues found across 2 files (changes from recent commits).
Tip: Review your code locally with the cubic CLI to iterate faster.
Re-trigger cubic
Revert 7cc5a94, which deleted dev/constitution.md and rewrote the dev/README description to claim the constitution body lives in dev/constitution.md with .specify/memory/constitution.md symlinking to it. That commit deferred both to PR #356, but #356 touches neither file (.specify/memory/constitution.md is a real 5.8K file, not a symlink), so the branch was left internally inconsistent: a deleted file that the README still linked to, and a symlink that does not exist. Restore dev/constitution.md as the pointer stub and revert the README to describe it as a pointer. All dev/ links resolve again and the diff now matches PR #358's description. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…roject Address two Cubic review findings on PR #358: - adding-a-doc-fragment.md: the extends_documentation_fragment example dropped the file basename. Fragments are attributes of ModuleDocFragment in plugins/doc_fragments/fragments.py, so the FQCN is opsmill.infrahub.fragments.<ATTRIBUTE>, not opsmill.infrahub.my_fragment. - 0003-sync-only-sdk.md: the SDK range said >=1.5,<2.0 but pyproject.toml pins infrahub-sdk[all]>=1.19.0,<2.0. Fix the same stale range where it also appeared in AGENTS.md and infrahub-sdk-usage.md (the latter also showed Poetry-style syntax under a "# pyproject.toml" comment; corrected to the real PEP 621 dependencies array). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Author dev/ developer docs (guides, guidelines, knowledge, ADRs)
Fills out the
dev/reference layer to match thestyrmin/infrahub-mcpconventions. All content is freshly authored about this collection and grounded in the real plugin code — no peer domain content copied.Added — guidelines
markdown.md— kebab-case naming + the real markdown tooling (.markdownlint.yaml, Vale, yamllint).module-docstrings.md—DOCUMENTATION/EXAMPLES/RETURNrules,doc_fragments, theinvoke generate-docpipeline..markdownlint.yml→.markdownlint.yamlreference in the existingpython.md+documentation.md.Added — guides
adding-a-doc-fragment.md—ModuleDocFragment+extends_documentation_fragment.debugging-sanity-failures.md— reproducing/fixingansible-test sanityfailures (boilerplate,HAS_INFRAHUBCLIENT, docstring/arg-spec mismatch).releasing-the-collection.md—invoke galaxy-build, the automated develop→stable version bump +workflow-publish.ymlGalaxy publish + release-drafter changelog (no invented commands).Added — knowledge
inventory-and-lookup.md— deep-dive on the inventory + lookup plugins.processors-and-arg-spec.md—INFRAHUB_ARG_SPEC+ thedeepcopy()extension pattern and theInfrahubBaseProcessor→InfrahubNodesProcessor/InfrahubQueryProcessorhierarchy.Added — ADRs (MADR, backfilling real decisions)
0001-two-plugin-patterns,0002-sdk-abstraction-wrapper,0003-sync-only-sdk,0004-docker-based-testing,0005-doc-generation-pipeline.Other
dev/constitution.md— pointer to.specify/memory/constitution.md(no body; avoids drift).dev/README.md— rewritten to the peer Quick-Navigation table, indexing every real file incl.../.agents/commands/.Final
dev/layer: 5 knowledge docs · 6 guidelines · 5 guides · 5 ADRs · README + constitution pointer.Verification
plugins/inventory/inventory.py,plugins/lookup/lookup.py, andinfrahub_utils.py— all cited classes/options/methods exist (InventoryModule,Cacheable,_mark_trusted,prefetch_relationships,InfrahubQueryProcessor,InfrahubBaseProcessor, …).dev/links resolve; ADRs followdev/adr/README.md's MADR format + numbering; filenames kebab-case; markdownlint reports 0 errors.dev-reference-layoutpasses; 0 errors.Two commits,
dev/only. Pure documentation — no code, schema, or behavior changes.🤖 Generated with Claude Code