Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

CHANGELOG.md entries are too long to maintain, and their length is what makes every PR conflict expensive

Chiusa Adatta ai principianti
  • Qualcosa non va?
#809 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
72/100
Tipo di issue
Documentazione
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
markdown
Ambito
documentation, release

Direzione di ricerca

Inizia da CHANGELOG.md e dev/release-1.8.0-prompt.md, quindi esamina i record a cui si fa riferimento in docs/adr/ e nell’issue #800. Definisci le indicazioni per le nuove voci in modo che siano composte da una o due frasi con riferimenti a issue, PR e ADR, lasciando inalterate le sezioni rilasciate; il lavoro è completato quando la regola è chiara per la migrazione dei frammenti e le release future.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

enhancement

Summary

Keep a Changelog entries are one line. Ours average 145 words and reach 828. Every entry is a paragraph inserted at the top of a shared section, which is what makes the conflicts in #800 expensive to resolve by hand. Expensive hand resolution is what produced the duplicate ### Added that #800 reports, so this is not a separate cosmetic complaint. It is the multiplier on that problem.

Measurements

Taken at f8d1dd2e.

measurement value
top-level entries 324
words per entry mean 145, median 91, max 828
entries over 200 words 104
[Unreleased] section 1,151 lines and 15,005 words, a third of the file
whole file 3,330 lines, 313 KB
growth since v1.6.0 on 2026-07-05 350 lines to 3,330 lines

The content is already written down somewhere better

docs/adr/ holds 145 records. ADR-0142, ADR-0144 and ADR-0145 run about 2,500 words each and cover the same three changes their changelog entries cover in 200 to 400 words. The seeds, the checkpoint curves and the McNemar p-values are ADR material. Repeating a compressed version of them in the changelog gives a reader neither the short answer nor the full one.

Nothing consumes the file

CHANGELOG.md is not in the docs build, not in packaging metadata, and not read by publish.yml. Its only readers are people and dev/release-1.8.0-prompt.md. A file that no tool reads and no person can finish reading is not doing its job.

Proposed rule

A changelog entry is one or two sentences saying what changed and what a reader has to do differently, plus references to the issue, the PR and the ADR. The rationale, the measurements and the alternatives considered stay in the ADR.

Scope is new entries only. Released sections are the record of what shipped and stay as they are.

Why this is worth doing before the fragment migration

#800 is heading toward one changelog fragment per change. A one-line entry needs no custom towncrier template and no wrapping rules, so adopting the rule first makes that migration smaller. Short entries also shrink every conflict hunk in the meantime.

References

  • #800 for the conflict problem and the fragment fix
Lingua principale
Python
Stelle
25
Fork
25
Merge medio
4h 13m
PR unite (30g)
97

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di lanl/PyBNF

Tutte le issue di lanl/PyBNF

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.