Write a Changelog That Tells Readers What Changed and What to Do

## Find Who Reads the Changelog and Which Changes Affect Them Write a changelog for people affected by software changes, not as a machine-validated specification or a raw dump of development activity. Every editorial choice should help a reader understand the release with less effort. Before drafting, identify: - The release or version being described. - The people who rely on the product, library, service, or documentation. - The changes that alter behavior, expectations, compatibility, accessibility, security, or required actions. - The established versioning, heading, and entry conventions already used by the project. Use conventions as tools, not as substitutes for judgment. Preserve an existing structure when it helps readers compare releases, but do not force a change into misleading wording merely to satisfy a label. When a rule must be strict, explain the reason so contributors can apply it intelligently. Keep changelog principles separate from setup instructions and routine contribution procedures. Maintain one authoritative location for each kind of guidance, and link to it instead of duplicating instructions that can drift. ## Include Only Changes That Affect Readers, and Say Why They Matter Review candidate changes from the reader's perspective. Include an item when it changes what a person can do, observe, depend on, configure, migrate, or protect. Exclude internal activity that has no meaningful effect unless it explains a relevant operational or compatibility consequence. For each included change, answer: 1. What changed in observable terms? 2. Who is affected and under what conditions? 3. Why does the change matter? 4. Does the reader need to act, and if so, what action is required? Lead with the outcome. Add only the context needed to prevent misunderstanding. State conditions, exceptions, and migration implications explicitly; do not hide them behind a vague summary. Do not promote a particular tool merely because it is popular, and do not invent a process that solves no demonstrated communication problem. Prefer a simple entry and the project's existing workflow unless the current approach prevents readers from understanding an important change. Guidelines and recommendations should include their rationale. A reader should be able to disagree intelligently because the tradeoff and intended benefit are visible. ## Write Each Change in Plain Words, With Its Effect and Any Action Needed Use plain language and put the point first. Avoid gatekeeping, insider shorthand, decorative complexity, and sentences that require a reader to reconstruct the main claim. Prefer wording that a non-native reader can understand on the first pass and that a translator can translate directly rather than reinterpret. Keep these elements distinct: - The change itself: a concrete description of the previous and new behavior. - The impact: the users, environments, versions, or workflows affected. - The reason: the problem solved or principle protected. - The action: any upgrade, configuration, migration, or verification step the reader must take. Do not overstate certainty or impact. If behavior varies by context, name the condition rather than issuing a universal command. If no reader action is required, do not manufacture one. Use terminology consistently across entries and versions. Explain unavoidable specialist terms on first use, preserve important distinctions, and avoid euphemisms that weaken warnings or breaking-change information. Apply the same clear, point-first style to related documentation, contribution notes, and commit messages so that the change record is supported by consistent source information. ## Make Sure Translations Match the Original Entry, With a Person Deciding Treat translations as first-class change communication. A version-specific translation must either exist or provide clear guidance for contributing it. It must remain accurate and consistent with the canonical source while also being understandable in its own language and cultural context. Keep page structure, version routing, and source markup simple enough for a non-programmer translator to edit. Before changing headings, identifiers, version relationships, or markup conventions, evaluate how the change affects every maintained language and version. Use this review sequence: 1. Finalize the canonical entry's meaning before translation. 2. Record which versions and languages require the change. 3. Check that each required translation exists or has a clear contribution path. 4. Compare translated meaning with the canonical source for omissions, reversals, altered conditions, and inconsistent terminology. 5. Have a person who knows the language and culture make the final editorial decision. Do not use machine-generated text as a substitute for a translator. Automated or model-assisted checks may locate missing coverage and possible inconsistencies, but people own the meaning, cultural fit, and final wording. ## Use Simple Tools for Repeated Checks, but Let People Decide Use automation to reduce repetitive verification across languages, versions, and presentation environments. Good candidates include translation-coverage checks, version-routing tests, semantic comparison aids, accessibility checks, and visual or functional regression tests. Prefer ordinary, reusable tools that can run locally or offline without a model after they are created. A language model may help design or implement a tool once, but the resulting check should be inspectable, repeatable, inexpensive to run, and able to stand on its own. Models must not: - Replace human translators or cultural review. - Decide the project's editorial positions or what its guidance means. - Justify a feature or process that has no independent need. Humans decide whether a changelog entry is accurate, useful, and appropriate. Tooling supplies evidence; it does not own the conclusion. Keep the publishing system simple and durable. Prefer the existing build and authoring toolchain, and add a dependency, service, database, or new runtime only when a concrete requirement cannot be met safely with the current approach. Development-only verification tools must not become unnecessary production requirements. Before publishing, confirm that the canonical entry is clear, required versions and translations are covered, automated checks have actual results, and a human has reviewed the final meaning.