Skip to content

docs(blog): deep dive into the OmegaConf inventory backend - #1543

Draft
Moep90 wants to merge 1 commit into
masterfrom
docs/blog-omegaconf-backend-deep-dive
Draft

docs(blog): deep dive into the OmegaConf inventory backend#1543
Moep90 wants to merge 1 commit into
masterfrom
docs/blog-omegaconf-backend-deep-dive

Conversation

@Moep90

@Moep90 Moep90 commented Jun 13, 2026

Copy link
Copy Markdown
Contributor

Draft until #1537 and #1538 (the SEO frontmatter gate) merge — this post depends on the title/description frontmatter those PRs enforce.

What

A new blog post, docs/pages/blog/posts/omegaconf-backend-deep-dive.md, walking through the OmegaConf inventory backend: what it gives us over reclass, how interpolation and deferred evaluation work, and the literal ${escape:...} syntax from #1445.

Why

The OmegaConf backend has grown some genuinely useful features that are easy to miss if you only know reclass — dot-notation interpolation, oc.select/oc.env defaults, conditional resolvers, deferred \${...} evaluation, and custom Python resolvers. The literal-vs-deferred escape distinction in particular trips people up constantly, and #1445 plus the doc clarifications in #1521 finally made it unambiguous. I wanted one practical, opinionated post that ties it together so people know when reaching for the backend is worth it.

Approach

First person, practical, in the established blog voice. Every flag, YAML snippet, and behaviour claim is grounded in the existing docs and source — I deliberately did not invent anything:

  • Install/enable/dotfile config and the --migrate migration table from docs/pages/inventory/omegaconf.md.
  • .yaml class support framed against fix(omegaconf): resolve --migrate flag and .yaml class support #1483.
  • The ${escape:...} literal behaviour, including the key-collision case and the __KAPITAN_LITERAL__ marker mechanism, taken straight from kapitan/inventory/backends/omegaconf/resolvers.py and the feat: add literal resolver to emit backslash dollar syntax in OmegaConf #1445 description.
  • Examples mirror the real test inventory in tests/test_resources/omegaconf/inventory/classes/components/test-resolvers.yml.
  • A !!! note admonition spells out the \${...} (deferred) vs ${escape:...} (literal) difference, since that is the single most common point of confusion.

Verification

  • Confirmed the YAML frontmatter parses and that title (46) and description (131) land inside the SEO gate ranges.
  • Cross-checked the escape behaviour and marker constants against the backend source rather than guessing.
  • Did not run pytest or build the docs site, per the scope of this change.

@github-actions github-actions Bot added documentation Anything related to documentation size/m labels Jun 13, 2026
@Moep90
Moep90 force-pushed the docs/blog-omegaconf-backend-deep-dive branch from 8da59e3 to 9d4b91e Compare June 13, 2026 06:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Anything related to documentation size/m

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant