Skip to content

Slice #22.1: Move included ADR/QS/R artifacts to section-level headings #23

Description

@dieterbaier

Parent: #22

Goal

Adopt the canonical heading policy from the parent issue discussion: architecture detail artifacts that are intended to be included into an assembled/wrapping document start at section level 1 (==), not document level 0 (=).

This applies at least to ADR, quality scenario, and risk artifacts.

Background

The parent issue initially considered preserving standalone = headings and compensating with leveloffset. The follow-up decision is different:

an ADR should start with Level 1 (== ...). If one would really like to have such a document rendered standalone on Level 0, you can still wrap that document with a dedicated Level 0 document

So the source artifacts themselves should match their normal include context.

Scope

  • Update templates/adr.adoc, templates/quality-scenario.adoc, and templates/risk.adoc so their first visible heading is ==.
  • Update existing root source artifacts:
    • src/docs/arc42/09-architecture-decisions/adr-*.adoc
    • src/docs/arc42/10-quality-requirements/qs-*.adoc
    • src/docs/arc42/11-risks-and-technical-debt/r-*.adoc
  • Update example templates and example ADR/QS/R source artifacts consistently, or explicitly defer example changes to the dogfood slice if that keeps review smaller.
  • Preserve YAML front matter, stable IDs, anchors, statuses, summaries, and traceability includes.
  • Check whether generated traceability fragments still land at the intended child level after the heading change.

Acceptance Criteria

  • ADR/QS/R templates start with ==, not =.
  • Existing ADR/QS/R source artifacts in the root docs start with ==, not =.
  • No level-0 heading remains in an included ADR/QS/R artifact.
  • Rendered root arc42 output no longer promotes ADR/QS/R artifacts to top-level sibling chapters.
  • Validation and render checks pass.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions