Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

Codify ADR amendment convention in AGENTS.md and pre-commit checks to prevent in-place modification of accepted decisions

Abierto
  • ¿Algo no está bien?
#288 2 comentarios 1 reacción 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
3/5
Tiempo estimado
1-2 días
Aptitud para principiantes
55/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
markdown, python
Área
documentation, tooling

Línea de trabajo

Start with the 'Rules for creating or modifying specification documents' section in AGENTS.md, where the proposed ADR amendment rule would go, and with the existing linters in scripts/lint.py and .pre-commit-config.yaml. Read docs/decisions/0001-requirements-storage-format.md to see the amendment format and what counts as a historical section. Done means the AGENTS.md rule is added and an offline check fails when an accepted ADR's existing lines are deleted or changed, while amendment blocks still pass. The check's exact rules for what counts as a historical section are not settled in the issue, so confirm them with maintainers first.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

enhancement feature infra ready-for-triage triaged

What happened

On PR #250 (https://github.com/redhat-et/ProtoBot/pull/250), commit 6e2ed1b modified docs/decisions/0001-requirements-storage-format.md by rewriting the accepted decision prose in place (lines 152–156) instead of appending a dated amendment section. Across automated review runs (including run 37943172659 on 6e2ed1b), the review agent reported zero findings on the ADR diff, raising only a generic [protected-path] finding on .github/workflows/ci-workflow.yaml. During subsequent human review, Lukas Kellerstein identified this in review comment A8 (https://github.com/redhat-et/ProtoBot/pull/250#pullrequestreview-2947118128): "Accepted ADR text rewritten in place: Mutated historical accepted ADR text rather than following the repo convention of appending a dated amendment section." Author John Strunk had to manually restore the historical decision text and append an **[Amended October 2026]** block in commit dc2d157.

What could go better

AGENTS.md explicitly lists docs/decisions/ as part of the specification document hierarchy and establishes detailed rules for creating and modifying specification documents, including registered artifact governance via ears-manager artifact put and sibling terminology consistency. However, AGENTS.md does not define rules for Architecture Decision Records, nor does it codify the project convention that accepted ADRs are immutable historical records that can only be refined by appending dated amendments (**[Amended Month Year]**). Furthermore, scripts/lint.py and .pre-commit-config.yaml contain linters for Markdown, YAML, and Go, but no deterministic check verifying that existing sections in accepted ADR files remain untouched. Because this convention was undocumented in agent instructions and unenforced by linters, neither the authoring workflow nor the review agent caught the mutation, requiring human reviewer intervention.

Proposed change

  1. In AGENTS.md, add a numbered rule under 'Rules for creating or modifying specification documents':
    "Accepted Architecture Decision Records (docs/decisions/) are immutable historical records. Never rewrite or replace accepted decision text in place. When subsequent design evolution amends or refines an accepted ADR, append a dated amendment block (**[Amended Month Year]**) describing the change, its rationale, and references to updated architecture documents. Review agents must verify that changes to accepted ADRs follow this amendment convention rather than modifying accepted sections in place."
  2. In scripts/lint.py, implement an offline pre-commit check verifying that git diffs touching files under docs/decisions/ with status 'Accepted' do not delete or modify lines in historical sections preceding the amendment blocks.

Validation criteria

The next 5 PRs (agent-generated or human-authored) touching docs/decisions/ adhere to the amendment convention without requiring human review comments or rework cycles, and review agents flag any in-place mutation to historical ADR decision sections as a finding.

Generated by retro agent from https://github.com/redhat-et/ProtoBot/pull/250

Lenguaje dominante
Go
Estrellas
6
Forks
8
Merge medio
1 d 4 h
PR fusionados (30 d)
90

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de redhat-et/ProtoBot

Todos los issues de redhat-et/ProtoBot

Issues similares

Más issues de Go

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.