> For the complete documentation index, see [llms.txt](https://engineering.umh.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://engineering.umh.app/engineering/development-process/how-to-ship/changelog.md). # Changelog How we tell users what changed in a release. Owner: Jeremy Customers run umh-core in their factories and update it themselves. A US government guide on patching control systems calls patching there "inconsistent at best and nonexistent at worst" ([DHS/CISA](https://www.cisa.gov/sites/default/files/recommended_practices/RP_Patch_Management_S508C.pdf)). We want customers to update as easily as they update any modern software. ## Rules * The changelog carries only changes the user can notice. The build pipeline, linting, tests and refactors are not user-facing. * Where there is no entry to write, set the repository's changelog-waiver label and say why in the pull request. * An entry starts with the feature it happens in. A fix says what the user saw go wrong, not what caused it. * Write entries in [the names we already use](/engineering/development-process/how-to-build/tickets.md#public-names) — such as bridge or Topic Browser — and in the terms of the protocol or tool the reader works with. Someone using the S7 plugin knows the word data block. ## Before the release [**Try the entries on someone else**](/engineering/development-process/how-to-build/coding-standards/code-quality/readability.md#try-it-on-someone-else) **who reads them as the user they concern.** [Keep a Changelog](https://keepachangelog.com/) puts it: "changelogs are for humans, not machines". ## When the user has to act **Breaking changes and exploitable vulnerabilities go under Action required.** The entry says what the user must do. An issue that turns out to be exploitable moves there too, and [Tickets › Security](/engineering/development-process/how-to-build/tickets/security.md#the-description) records whether it is exploitable. ## Changes that need another release **Write what the product can now do, and say it might not be available in the other product yet.** The release that displays it does not exist when you write, so there is no version to name. **The entry in the product that displays it names the version it needs:** ```markdown umh-core, Improvements: - umh-core can now report memory health to the Management Console. It might not be available there yet. Management Console, New Features: - Container and machine memory health on the instance page. Requires umh-core 0.45.0 or later. ``` ## Sections **In this order, leaving out the empty ones:** 1. Action required: breaking changes and exploitable vulnerabilities. 2. New Features 3. Improvements 4. Fixes 5. Security updates: every other security fix, in our code or in a dependency. 6. Preview: features behind a [feature flag](/engineering/development-process/how-to-ship.md#why-a-feature-flag) the user can turn on. The entry says how to switch the feature on. **These six are where we are going, and a repository can produce them only once its changelog does.** Where [changie](https://changie.dev) generates the changelog, the kinds in its config are what exist. Where it is written by hand, the changelog site's validator decides, and umh-core runs that validator on every pull request that touches the changelog ([validate-changelog.ts](https://github.com/united-manufacturing-hub/changelog.umh.app/blob/main/.github/scripts/validate-changelog.ts), UMH only). **Until then, use the nearest section the repository can produce and name the one you meant in the pull request.** Action required becomes Breaking Changes; Security updates and Preview become Fixes. Adding a kind to a config changes every release the repository generates. ## Security fixes **The Action required entry for an exploitable vulnerability:** ```markdown - Fixed a vulnerability that let ([CWE-nnn]()). Affects versions before . Update now. ``` The actor comes from the [threat model](/engineering/development-process/how-to-build/coding-standards/architecture/security.md#actors). **Dependencies with known vulnerabilities get one grouped entry, and it lists the advisories the release clears.** Name the feature each flaw was reachable through. An upgrade that clears none of a dependency's advisories is not listed. ```markdown - Updated dependencies with known vulnerabilities: - , now — reachable only through (, ) - , now () Update to reduce your attack surface. ``` **A flaw still open somewhere else — a bundled binary, another repository — stays out.** Disclosing an unfixed flaw is a separate decision. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://engineering.umh.app/engineering/development-process/how-to-ship/changelog.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.