Skip to content

chore(release): introduce CHANGELOG + ADR-index fragment files (drop merge-conflict pain)#228

Closed
lusoris wants to merge 0 commit intomasterfrom
chore/dedup-changelog-adr-fragments
Closed

chore(release): introduce CHANGELOG + ADR-index fragment files (drop merge-conflict pain)#228
lusoris wants to merge 0 commit intomasterfrom
chore/dedup-changelog-adr-fragments

Conversation

@lusoris
Copy link
Copy Markdown
Owner

@lusoris lusoris commented Apr 29, 2026

Summary

What's added

CHANGELOG fragments

  • changelog.d/{added,changed,deprecated,removed,fixed,security}/<topic>.md — one Markdown bullet (or block) per PR, lexically sorted within section.
  • changelog.d/_pre_fragment_legacy.md — verbatim archive of pre-fragment Unreleased content.
  • scripts/release/concat-changelog-fragments.sh — --check (CI gate) + --write (release-please / pre-push).

ADR-index fragments

  • docs/adr/_index_fragments/<NNNN-slug>.md — one Markdown table row per ADR, slug-keyed (handles legacy ADR-0199 collision).
  • docs/adr/_index_fragments/_order.txt — frozen commit-merge order manifest. New PRs append one slug; trivial conflict resolution.
  • docs/adr/_index_fragments/_header.md — verbatim README prelude.
  • scripts/docs/concat-adr-index.sh — --check + --write.

Wiring

  • Makefile: new docs-fragments-check (added to make lint) and docs-fragments-write targets.
  • .github/PULL_REQUEST_TEMPLATE.md updated to instruct fragment-only CHANGELOG/ADR-index workflow.
  • .github/workflows/rule-enforcement.yml: ADR-0108 deliverable check now accepts changelog.d/<section>/*.md as a CHANGELOG entry.
  • AGENTS.md §8 + §9(e) reference ADR-0221.
  • docs/rebase-notes.md §0221 entry for upstream-sync invariance.

Compatibility with in-flight PRs

The legacy direct-edit path still works during migration: a PR that edits CHANGELOG.md directly will pass the ADR-0108 deliverables check. After this PR merges, the rendered Unreleased block matches the in-tree CHANGELOG.md byte-for-byte, so any in-flight PR's CHANGELOG.md hunk applies cleanly. New PRs should switch to fragments going forward.

Test plan

  • bash scripts/release/concat-changelog-fragments.sh --check exits 0 (verified locally).
  • bash scripts/docs/concat-adr-index.sh --check exits 0 (verified locally).
  • make docs-fragments-check exits 0 (new Makefile target).
  • bash scripts/release/concat-changelog-fragments.sh --write is idempotent (no diff after running on the migrated tree).
  • bash scripts/docs/concat-adr-index.sh --write is idempotent.
  • Adding a sample fragment (changelog.d/changed/T7-39-changelog-adr-fragments.md) renders correctly into the Unreleased block.
  • Adding a sample ADR-index fragment (docs/adr/_index_fragments/0221-...md) + appending the slug to _order.txt renders the new row at the bottom of docs/adr/README.md.

Reproducer

# After cloning at this branch:
make docs-fragments-check
bash scripts/release/concat-changelog-fragments.sh --write   # idempotent
bash scripts/docs/concat-adr-index.sh --write                # idempotent
git diff   # should be empty

Deep-dive deliverables (ADR-0108)

  • Research digest — docs/research/0034-changelog-fragment-pattern.md documents the cost-of-merge-conflict measurement and the changie / towncrier / release-please-native alternatives evaluated.
  • Decision matrix — ADR-0221 § Alternatives considered.
  • AGENTS.md invariant note — AGENTS.md §8 (ADR-index fragments) + §9(e) (CHANGELOG fragments).
  • Reproducer / smoke-test command — see "Test plan / Reproducer" above.
  • CHANGELOG fragment — changelog.d/changed/T7-39-changelog-adr-fragments.md.
  • Rebase note — docs/rebase-notes.md §0221.

Bug-status hygiene (ADR-0165)

no state delta: process / release-tooling change with no bug-status impact.

Netflix golden-data gate (ADR-0024)

  • No assertAlmostEqual(...) modifications.

Known follow-ups

  • T7-39b: wire scripts/release/concat-changelog-fragments.sh --write into .github/workflows/release-please.yml so the rendered Unreleased block is the input release-please consumes. Out of scope for this PR; tracked separately.
  • Legacy archive collapse: at the next release tag, changelog.d/_pre_fragment_legacy.md content rolls into a versioned section and the archive can be deleted. Optional clean-up follow-up.

🤖 Generated with Claude Code

Copilot AI review requested due to automatic review settings May 1, 2026 18:13
@lusoris lusoris closed this May 1, 2026
@lusoris lusoris force-pushed the chore/dedup-changelog-adr-fragments branch from 54ec877 to 3130ca4 Compare May 1, 2026 18:13
Copilot AI reviewed May 1, 2026
View reviewed changes
Copy link
Copy Markdown

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.

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

@lusoris lusoris mentioned this pull request May 1, 2026
Merged
14 tasks
lusoris pushed a commit that referenced this pull request May 3, 2026
@claude
docs(vulkan): T-VK-1.4-BUMP — root-cause investigation, defer 1.4 bum…
b97655a 
…p (ADR-0257)

Captures the deep-dive on the NVIDIA-only cross-backend regression that
surfaces when VkApplicationInfo.apiVersion is bumped from
VK_API_VERSION_1_3 to VK_API_VERSION_1_4. Docs-only PR — no code change
on master.

Findings:
- Compiled SPIR-V is byte-identical at glslc --target-env=vulkan1.3 vs
  vulkan1.4 for both vif.comp and ciede.comp (verified via cmp). The
  regression is purely runtime — NVIDIA's shader compiler flips its
  default FMA-contraction policy under core shaderFloatControls2
  (promoted to Vulkan 1.4).
- Vulkan SPIR-V exposes no module-wide ContractionOff execution mode
  (Kernel-capability only); the only knob is per-result OpDecorate
  NoContraction (GLSL precise).
- The fork has no in-flight requirement for any 1.4-promoted feature,
  so deferring the bump is operationally free.

Decision: defer the bump and track the two-step fix as backlog item
T-VK-1.4-BUMP — (A) tag load-bearing FP ops 'precise' in vif.comp +
ciede.comp, (B) bump only after the gate is clean on NVIDIA + RADV +
lavapipe at places=4.

Adds:
- ADR-0257 (Accepted) and research-0053 with the full investigation
  trail, prototypes, and decision matrix.
- AGENTS.md invariant note in libvmaf/src/vulkan/ pinning the four
  apiVersion / VMA_VULKAN_VERSION sites at 1.3.
- T-VK-1.4-BUMP row in docs/state.md Deferred section.
- CHANGELOG entry + rebase-notes #228.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@lusoris lusoris mentioned this pull request May 3, 2026
Merged
14 tasks
lusoris pushed a commit that referenced this pull request May 3, 2026
@claude
feat(tools): vmaf-tune encode.py — codec-agnostic dispatcher (unblock…
01eb63b 
…s 17 adapters)

Refactors `tools/vmaf-tune/src/vmaftune/encode.py` away from the Phase A
hard-coded `libx264` `-c:v / -preset / -crf` argv. `run_encode` now
looks up the codec adapter via `codec_adapters.get_adapter(req.encoder)`
and asks it for the FFmpeg argv slice via
`adapter.ffmpeg_codec_args(preset, quality)` plus an optional
`adapter.extra_params()`. Adapters that don't yet expose
`ffmpeg_codec_args` fall back silently to the legacy x264-CRF shape so
partial in-flight adapter PRs stay drivable end-to-end.
`parse_versions(stderr, encoder=...)` selects a per-codec version probe
(libx264, libx265, libsvtav1, libvpx-vp9, libaom-av1, libvvenc, NVENC,
QSV, AMF, VideoToolbox); unknown encoders return "unknown" rather than
raising. The `EncodeRequest.crf` field is preserved unchanged for the
SCHEMA_VERSION=1 row contract; a `quality` property mirrors it for
adapter-side codec-agnostic vocabulary.

Existing 13-test x264 suite still green; new 19-test multi-codec suite
covers 9 representative codec shapes plus the unknown-codec /
missing-method fallback paths. Unblocks 17 in-flight codec adapter PRs
(#360 libaom, #362 libx265, #364 NVENC, #366 AMF, #367 QSV, #368
libvvenc, #370 libsvtav1, #373 VideoToolbox, plus follow-on waves)
which can now drive end-to-end encodes without copying or mutating the
harness.

Ships ADR-0294 + research digest 0054, vmaf-tune.md "Codec adapter
contract" section, rebase-notes #228 invariant, CHANGELOG entry.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
lusoris pushed a commit that referenced this pull request May 4, 2026
@claude
docs(vulkan): T-VK-1.4-BUMP — root-cause investigation, defer 1.4 bum…
0b9ca81 
…p (ADR-0257)

Captures the deep-dive on the NVIDIA-only cross-backend regression that
surfaces when VkApplicationInfo.apiVersion is bumped from
VK_API_VERSION_1_3 to VK_API_VERSION_1_4. Docs-only PR — no code change
on master.

Findings:
- Compiled SPIR-V is byte-identical at glslc --target-env=vulkan1.3 vs
  vulkan1.4 for both vif.comp and ciede.comp (verified via cmp). The
  regression is purely runtime — NVIDIA's shader compiler flips its
  default FMA-contraction policy under core shaderFloatControls2
  (promoted to Vulkan 1.4).
- Vulkan SPIR-V exposes no module-wide ContractionOff execution mode
  (Kernel-capability only); the only knob is per-result OpDecorate
  NoContraction (GLSL precise).
- The fork has no in-flight requirement for any 1.4-promoted feature,
  so deferring the bump is operationally free.

Decision: defer the bump and track the two-step fix as backlog item
T-VK-1.4-BUMP — (A) tag load-bearing FP ops 'precise' in vif.comp +
ciede.comp, (B) bump only after the gate is clean on NVIDIA + RADV +
lavapipe at places=4.

Adds:
- ADR-0257 (Accepted) and research-0053 with the full investigation
  trail, prototypes, and decision matrix.
- AGENTS.md invariant note in libvmaf/src/vulkan/ pinning the four
  apiVersion / VMA_VULKAN_VERSION sites at 1.3.
- T-VK-1.4-BUMP row in docs/state.md Deferred section.
- CHANGELOG entry + rebase-notes #228.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
lusoris pushed a commit that referenced this pull request May 4, 2026
@claude
docs(vulkan): T-VK-1.4-BUMP — root-cause investigation, defer 1.4 bum…
068e7bd 
…p (ADR-0257)

Captures the deep-dive on the NVIDIA-only cross-backend regression that
surfaces when VkApplicationInfo.apiVersion is bumped from
VK_API_VERSION_1_3 to VK_API_VERSION_1_4. Docs-only PR — no code change
on master.

Findings:
- Compiled SPIR-V is byte-identical at glslc --target-env=vulkan1.3 vs
  vulkan1.4 for both vif.comp and ciede.comp (verified via cmp). The
  regression is purely runtime — NVIDIA's shader compiler flips its
  default FMA-contraction policy under core shaderFloatControls2
  (promoted to Vulkan 1.4).
- Vulkan SPIR-V exposes no module-wide ContractionOff execution mode
  (Kernel-capability only); the only knob is per-result OpDecorate
  NoContraction (GLSL precise).
- The fork has no in-flight requirement for any 1.4-promoted feature,
  so deferring the bump is operationally free.

Decision: defer the bump and track the two-step fix as backlog item
T-VK-1.4-BUMP — (A) tag load-bearing FP ops 'precise' in vif.comp +
ciede.comp, (B) bump only after the gate is clean on NVIDIA + RADV +
lavapipe at places=4.

Adds:
- ADR-0257 (Accepted) and research-0053 with the full investigation
  trail, prototypes, and decision matrix.
- AGENTS.md invariant note in libvmaf/src/vulkan/ pinning the four
  apiVersion / VMA_VULKAN_VERSION sites at 1.3.
- T-VK-1.4-BUMP row in docs/state.md Deferred section.
- CHANGELOG entry + rebase-notes #228.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
lusoris added a commit that referenced this pull request May 4, 2026
@lusoris @claude
docs(vulkan): T-VK-1.4-BUMP — root-cause investigation, defer 1.4 bum…
5607a69 
…p (ADR-0257) (#338)

Captures the deep-dive on the NVIDIA-only cross-backend regression that
surfaces when VkApplicationInfo.apiVersion is bumped from
VK_API_VERSION_1_3 to VK_API_VERSION_1_4. Docs-only PR — no code change
on master.

Findings:
- Compiled SPIR-V is byte-identical at glslc --target-env=vulkan1.3 vs
  vulkan1.4 for both vif.comp and ciede.comp (verified via cmp). The
  regression is purely runtime — NVIDIA's shader compiler flips its
  default FMA-contraction policy under core shaderFloatControls2
  (promoted to Vulkan 1.4).
- Vulkan SPIR-V exposes no module-wide ContractionOff execution mode
  (Kernel-capability only); the only knob is per-result OpDecorate
  NoContraction (GLSL precise).
- The fork has no in-flight requirement for any 1.4-promoted feature,
  so deferring the bump is operationally free.

Decision: defer the bump and track the two-step fix as backlog item
T-VK-1.4-BUMP — (A) tag load-bearing FP ops 'precise' in vif.comp +
ciede.comp, (B) bump only after the gate is clean on NVIDIA + RADV +
lavapipe at places=4.

Adds:
- ADR-0257 (Accepted) and research-0053 with the full investigation
  trail, prototypes, and decision matrix.
- AGENTS.md invariant note in libvmaf/src/vulkan/ pinning the four
  apiVersion / VMA_VULKAN_VERSION sites at 1.3.
- T-VK-1.4-BUMP row in docs/state.md Deferred section.
- CHANGELOG entry + rebase-notes #228.

Co-authored-by: Lusoris <lusoris@pm.me>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
lusoris pushed a commit that referenced this pull request May 5, 2026
@claude
feat(tools): vmaf-tune encode.py — codec-agnostic dispatcher (unblock…
607c242 
…s 17 adapters)

Refactors `tools/vmaf-tune/src/vmaftune/encode.py` away from the Phase A
hard-coded `libx264` `-c:v / -preset / -crf` argv. `run_encode` now
looks up the codec adapter via `codec_adapters.get_adapter(req.encoder)`
and asks it for the FFmpeg argv slice via
`adapter.ffmpeg_codec_args(preset, quality)` plus an optional
`adapter.extra_params()`. Adapters that don't yet expose
`ffmpeg_codec_args` fall back silently to the legacy x264-CRF shape so
partial in-flight adapter PRs stay drivable end-to-end.
`parse_versions(stderr, encoder=...)` selects a per-codec version probe
(libx264, libx265, libsvtav1, libvpx-vp9, libaom-av1, libvvenc, NVENC,
QSV, AMF, VideoToolbox); unknown encoders return "unknown" rather than
raising. The `EncodeRequest.crf` field is preserved unchanged for the
SCHEMA_VERSION=1 row contract; a `quality` property mirrors it for
adapter-side codec-agnostic vocabulary.

Existing 13-test x264 suite still green; new 19-test multi-codec suite
covers 9 representative codec shapes plus the unknown-codec /
missing-method fallback paths. Unblocks 17 in-flight codec adapter PRs
(#360 libaom, #362 libx265, #364 NVENC, #366 AMF, #367 QSV, #368
libvvenc, #370 libsvtav1, #373 VideoToolbox, plus follow-on waves)
which can now drive end-to-end encodes without copying or mutating the
harness.

Ships ADR-0294 + research digest 0054, vmaf-tune.md "Codec adapter
contract" section, rebase-notes #228 invariant, CHANGELOG entry.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
lusoris added a commit that referenced this pull request May 5, 2026
@lusoris @claude
feat(tools): vmaf-tune encode.py — codec-agnostic dispatcher (unblock…
da5588d 
…s 17 adapters) (#376)

* feat(tools): vmaf-tune encode.py — codec-agnostic dispatcher (unblocks 17 adapters)

Refactors `tools/vmaf-tune/src/vmaftune/encode.py` away from the Phase A
hard-coded `libx264` `-c:v / -preset / -crf` argv. `run_encode` now
looks up the codec adapter via `codec_adapters.get_adapter(req.encoder)`
and asks it for the FFmpeg argv slice via
`adapter.ffmpeg_codec_args(preset, quality)` plus an optional
`adapter.extra_params()`. Adapters that don't yet expose
`ffmpeg_codec_args` fall back silently to the legacy x264-CRF shape so
partial in-flight adapter PRs stay drivable end-to-end.
`parse_versions(stderr, encoder=...)` selects a per-codec version probe
(libx264, libx265, libsvtav1, libvpx-vp9, libaom-av1, libvvenc, NVENC,
QSV, AMF, VideoToolbox); unknown encoders return "unknown" rather than
raising. The `EncodeRequest.crf` field is preserved unchanged for the
SCHEMA_VERSION=1 row contract; a `quality` property mirrors it for
adapter-side codec-agnostic vocabulary.

Existing 13-test x264 suite still green; new 19-test multi-codec suite
covers 9 representative codec shapes plus the unknown-codec /
missing-method fallback paths. Unblocks 17 in-flight codec adapter PRs
(#360 libaom, #362 libx265, #364 NVENC, #366 AMF, #367 QSV, #368
libvvenc, #370 libsvtav1, #373 VideoToolbox, plus follow-on waves)
which can now drive end-to-end encodes without copying or mutating the
harness.

Ships ADR-0294 + research digest 0054, vmaf-tune.md "Codec adapter
contract" section, rebase-notes #228 invariant, CHANGELOG entry.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore(docs): renumber encode-multi-codec ADR 0294→0297 + research 0069→0070

---------

Co-authored-by: Lusoris <lusoris@pm.me>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@lusoris