|
| 1 | +# Working on Keep a Changelog |
| 2 | + |
| 3 | +This file explains why the project is built the way it is. When a change |
| 4 | +conflicts with these principles, the principles win. |
| 5 | + |
| 6 | +How-to guidance — setup, common tasks, and the translation workflow — lives |
| 7 | +exclusively in [CONTRIBUTING.md](CONTRIBUTING.md). Do not repeat it here; |
| 8 | +point to it instead. |
| 9 | + |
| 10 | +## What this project is |
| 11 | + |
| 12 | +Keep a Changelog is a set of mindful guidelines for human-centered change |
| 13 | +communication. It is not a spec for people to robotically validate against. |
| 14 | +The site exists to help people communicate software changes to other humans, |
| 15 | +and every decision — in the writing and in the code — serves that goal. |
| 16 | + |
| 17 | +The project has one maintainer, myriad contributors, and an oversized impact |
| 18 | +on how software changes are communicated around the world. Most of that impact |
| 19 | +comes from refusing easy tropes: we do not create or endorse specific tools, |
| 20 | +we do not follow conventions blindly when they make little sense, and we do |
| 21 | +not tell people what to do without regard for their specific contexts. |
| 22 | + |
| 23 | +Apply the same judgment to the project itself. Favor simplicity, and when a |
| 24 | +rule needs to be strict, make the reasoning for that strictness clear. |
| 25 | + |
| 26 | +## Technical principles |
| 27 | + |
| 28 | +**No backend.** The site is static HTML, built once and served from GitHub |
| 29 | +Pages. This keeps hosting simple, cheap, and durable. Do not introduce |
| 30 | +anything that requires a server, a database, or a build service beyond the |
| 31 | +existing static build. |
| 32 | + |
| 33 | +**Ruby at heart, CLI-based.** This is a Ruby project (Middleman, Rake, |
| 34 | +Minitest), and every workflow runs from the command line ([CONTRIBUTING.md](CONTRIBUTING.md) |
| 35 | +lists the tasks). Prefer extending the existing Ruby and Rake tooling over |
| 36 | +adding new toolchains. Small exceptions exist where a tool is clearly the |
| 37 | +right one for the job (Playwright for cross-browser visual regression, a |
| 38 | +Python script for translation QA scoring) — they are dev-only and never part |
| 39 | +of the shipped site. |
| 40 | + |
| 41 | +**Boring is fine.** We do not need the most hyped language or framework. |
| 42 | +The measure of a tool is whether the project is hindered without it, not |
| 43 | +whether it is popular. Before proposing a migration or a new dependency, ask |
| 44 | +what problem it solves that the current setup cannot. |
| 45 | + |
| 46 | +**Translations are a first-class concern.** The site's incredible number of |
| 47 | +community-created translations exists because translating and managing |
| 48 | +versions is deliberately accessible — to readers and to contributors. A |
| 49 | +translator can edit plain markup without understanding the build (the workflow |
| 50 | +is in [CONTRIBUTING.md](CONTRIBUTING.md)). Protect that: any change to how |
| 51 | +pages are structured or versioned must remain easy for a non-programmer |
| 52 | +translator to follow. |
| 53 | + |
| 54 | +## How we use LLMs |
| 55 | + |
| 56 | +Keep a Changelog has one maintainer and myriad contributors. Keeping a free |
| 57 | +open source project like this alive involves complicated logistics: dozens of |
| 58 | +languages, several spec versions in each, and a steady stream of contributions |
| 59 | +to review. That work does not happen without automation — and even automation |
| 60 | +requires maintenance. LLMs help carry that load, within strict limits, because |
| 61 | +wasting resources is antithetical to what this project stands for. |
| 62 | + |
| 63 | +LLMs are **not** used to: |
| 64 | + |
| 65 | +- **Replace translators.** Translations are created and reviewed by people who |
| 66 | + speak the language and know the culture. No model output can substitute for |
| 67 | + that judgment. |
| 68 | +- **Decide what Keep a Changelog says.** The guidelines are human positions, |
| 69 | + reasoned about and owned by humans. |
| 70 | +- **Spend tokens on needless features.** If a feature would not exist without |
| 71 | + an LLM to justify it, it should not exist. |
| 72 | + |
| 73 | +LLMs **are** used to: |
| 74 | + |
| 75 | +- **Build reusable tools that do not need an LLM to run.** The translation |
| 76 | + coverage lint, the semantic QA pipeline, and the version routing tests are |
| 77 | + ordinary scripts anyone can run, offline, for free, forever. An LLM may help |
| 78 | + write a tool once; the tool must then stand on its own. |
| 79 | +- **Validate accessibility, design, and functionality requirements** — checks |
| 80 | + a single maintainer could not perform by hand across every language, version, |
| 81 | + and browser. |
| 82 | + |
| 83 | +The most daunting recurring problem this addresses is translation upkeep. |
| 84 | +Every version-specific translation must: |
| 85 | + |
| 86 | +1. exist — or the site must give clear guidance for contributing one; |
| 87 | +2. be accurate and consistent with the original English guidelines, while |
| 88 | + remaining understandable in its own language and culture. |
| 89 | + |
| 90 | +Tooling helps check these. Humans decide them. |
| 91 | + |
| 92 | +## Writing and content |
| 93 | + |
| 94 | +The content is held to `docs/tone-and-voice.md`. In short: write plainly, |
| 95 | +lead with the point, don't gatekeep, and prefer wording a non-native reader |
| 96 | +can understand on the first pass and a translator can translate rather than |
| 97 | +rephrase. This applies to site content, and it is a good default for |
| 98 | +documentation and commit messages too. |
| 99 | + |
| 100 | +Guidelines on the site should explain their reasoning. A reader should be able |
| 101 | +to disagree intelligently with any recommendation we make, because we told |
| 102 | +them why we make it. |
0 commit comments