Skip to content

Add stale-release guards for changelog-writing workflows #145

@coisa

Description

@coisa

Problem

DevTools now has a meaningful changelog and release workflow, but one failure mode remains easy to hit during issue-to-branch implementation work: starting a new feature branch from a stale local main can leave CHANGELOG.md and other release-sensitive files behind the latest published baseline.

When that happens, a new implementation may place changelog entries into the wrong section or carry forward stale release state even though the command or workflow logic itself is correct.

Proposal

Add explicit release-state guards that detect stale branching or stale changelog baselines before changelog entries or release-sensitive updates are written.

Goals

  • Prevent changelog entries from being inserted into already released sections because the branch did not start from an up-to-date baseline.
  • Make stale branching problems obvious and actionable instead of silently producing incorrect changelog state.
  • Protect release-sensitive workflows without making normal feature work harder than necessary.

Expected Behavior

Before a changelog-writing or release-sensitive workflow proceeds, DevTools should detect whether the local baseline is stale relative to the expected integration branch or the latest release state. When the repository is behind in a way that could misplace changelog content, the tool should stop with a clear diagnostic or require an explicit override if that is ever supported.

Implementation Strategy

  1. Identify the narrowest safe checkpoints where stale baseline detection matters most.
  2. Introduce a reusable release-state or changelog-baseline guard instead of scattering ad hoc checks.
  3. Integrate the guard into the relevant changelog-writing or issue-to-PR workflows.
  4. Add tests that reproduce stale-branch scenarios and verify the resulting diagnostics.
  5. Document the expected recovery path for maintainers.

Scope

  • Guard logic for stale changelog or release baseline detection.
  • Integration with the most relevant command or workflow surfaces.
  • Documentation and tests for the failure mode.

Non-goals

  • Do not redesign the full release workflow in this issue.
  • Do not require network access at every command invocation if a narrower safety check is sufficient.
  • Do not bundle unrelated changelog UX improvements into the same change.

Acceptance Criteria

Functional Criteria

  • DevTools detects stale changelog or release baseline conditions that could place new changes into an already published release section.
  • The affected command or workflow fails with a clear, actionable diagnostic instead of silently writing incorrect changelog state.
  • Focused tests reproduce the stale-branch scenario and verify the protection.
  • Documentation explains the guard and the expected maintainer recovery path.

Architectural / Isolation Criteria

  • MUST: The core logic MUST be isolated into dedicated classes or services instead of living inside command or controller entrypoints.
  • MUST: Responsibilities MUST be separated across input resolution, domain logic, processing or transformation, and output rendering when the change is non-trivial.
  • MUST: The command or controller layer MUST act only as an orchestrator.
  • MUST: The implementation MUST avoid tight coupling between core behavior and CLI or framework-specific I/O.
  • MUST: The design MUST allow future extraction or reuse with minimal changes.
  • MUST: The solution MUST remain extensible without requiring major refactoring for adjacent use cases.
  • MUST: Argument and option resolution MUST be validated separately from command execution logic.
  • MUST: Console formatting and rendering MUST stay separate from domain processing.
  • MUST: Exit behavior, error messaging, and generated output MUST remain deterministic and testable.

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

Status

Backlog

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions