Skip to content

docs(architecture): add ADR for template extends#582

Open
arodage wants to merge 8 commits into
mainfrom
feature/adr-template-extends
Open

docs(architecture): add ADR for template extends#582
arodage wants to merge 8 commits into
mainfrom
feature/adr-template-extends

Conversation

@arodage
Copy link
Copy Markdown
Contributor

@arodage arodage commented May 26, 2026

Merge Checklist

All boxes should be checked before merging the PR

  • The changes in the PR have been built and tested
  • Documentation has been updated to reflect the changes (or no doc update needed)
  • Ready to merge

Description

Adds an Architecture Decision Record (ADR) proposing extends support for image templates.

Problem: Users who need to customize existing templates must copy the entire template and modify it. When the original template is updated, every copy must be manually re-synchronized.

Proposal: Add an optional extends field to user templates that enables linear inheritance chains. Each template may extend at most one parent (single inheritance, no diamond problem). The merge is applied iteratively using the existing MergeConfigurations() as a fold operation, producing deterministic results at any chain depth.

Key design decisions:

  • Reuses existing MergeConfigurations() applied iteratively (OS defaults -> root -> level 1 -> ... -> leaf)
  • Single extends per template (no multiple inheritance) keeps merge deterministic
  • Cycle detection via visited-set check
  • Validation for target mismatches across the chain
  • Depth warning at 4+ levels (soft limit, no hard cap)
  • New resolve subcommand to inspect the merged result
  • Local file paths only (no remote URL support initially)

Any Newly Introduced Dependencies

None. This is a documentation-only change.

How Has This Been Tested?

Documentation-only change. No code changes to test.

@arodage arodage requested a review from a team as a code owner May 26, 2026 20:10
Copilot AI review requested due to automatic review settings May 26, 2026 20:10
@arodage arodage requested a review from a team as a code owner May 26, 2026 20:10
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new Architecture Decision Record (ADR) proposing single-level extends support for image templates, documenting the motivation, merge approach (defaults → parent → child), validation rules, and expected consequences within ICT’s template merge system.

Changes:

  • Introduces a proposed ADR describing the extends field semantics and constraints (single-level only, target match, circular/chained rejection).
  • Documents the intended merge flow leveraging existing MergeConfigurations() calls.
  • Captures risks/mitigations and alternatives considered for template reuse.

Comment thread docs/architecture/adr-template-extends.md Outdated
Comment thread docs/architecture/adr-template-extends.md Outdated
@arodage arodage changed the title docs(architecture): add ADR for single-level template extends docs(architecture): add ADR for template extends May 31, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants