{"owner":"olivierlacan","repo":"keep-a-changelog","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Working on Keep a Changelog\n\nThis file explains why the project is built the way it is. When a change\nconflicts with these principles, the principles win.\n\nHow-to guidance — setup, common tasks, and the translation workflow — lives\nexclusively in [CONTRIBUTING.md](CONTRIBUTING.md). Do not repeat it here;\npoint to it instead.\n\n## What this project is\n\nKeep a Changelog is a set of mindful guidelines for human-centered change\ncommunication. It is not a spec for people to robotically validate against.\nThe site exists to help people communicate software changes to other humans,\nand every decision — in the writing and in the code — serves that goal.\n\nThe project has one maintainer, myriad contributors, and an oversized impact\non how software changes are communicated around the world. Most of that impact\ncomes from refusing easy tropes: we do not create or endorse specific tools,\nwe do not follow conventions blindly when they make little sense, and we do\nnot tell people what to do without regard for their specific contexts.\n\nApply the same judgment to the project itself. Favor simplicity, and when a\nrule needs to be strict, make the reasoning for that strictness clear.\n\n## Technical principles\n\n**No backend.** The site is static HTML, built once and served from GitHub\nPages. This keeps hosting simple, cheap, and durable. Do not introduce\nanything that requires a server, a database, or a build service beyond the\nexisting static build.\n\n**Ruby at heart, CLI-based.** This is a Ruby project (Middleman, Rake,\nMinitest), and every workflow runs from the command line ([CONTRIBUTING.md](CONTRIBUTING.md)\nlists the tasks). Prefer extending the existing Ruby and Rake tooling over\nadding new toolchains. Small exceptions exist where a tool is clearly the\nright one for the job (Playwright for cross-browser visual regression, a\nPython script for translation QA scoring) — they are dev-only and never part\nof the shipped site.\n\n**Boring is fine.** We do not need the most hyped language or framework.\nThe measure of a tool is whether the project is hindered without it, not\nwhether it is popular. Before proposing a migration or a new dependency, ask\nwhat problem it solves that the current setup cannot.\n\n**Translations are a first-class concern.** The site's incredible number of\ncommunity-created translations exists because translating and managing\nversions is deliberately accessible — to readers and to contributors. A\ntranslator can edit plain markup without understanding the build (the workflow\nis in [CONTRIBUTING.md](CONTRIBUTING.md)). Protect that: any change to how\npages are structured or versioned must remain easy for a non-programmer\ntranslator to follow.\n\n## How we use LLMs\n\nKeep a Changelog has one maintainer and myriad contributors. Keeping a free\nopen source project like this alive involves complicated logistics: dozens of\nlanguages, several spec versions in each, and a steady stream of contributions\nto review. That work does not happen without automation — and even automation\nrequires maintenance. LLMs help carry that load, within strict limits, because\nwasting resources is antithetical to what this project stands for.\n\nLLMs are **not** used to:\n\n- **Replace translators.** Translations are created and reviewed by people who\n  speak the language and know the culture. No model output can substitute for\n  that judgment.\n- **Decide what Keep a Changelog says.** The guidelines are human positions,\n  reasoned about and owned by humans.\n- **Spend tokens on needless features.** If a feature would not exist without\n  an LLM to justify it, it should not exist.\n\nLLMs **are** used to:\n\n- **Build reusable tools that do not need an LLM to run.** The translation\n  coverage lint, the semantic QA pipeline, and the version routing tests are\n  ordinary scripts anyone can run, offline, for free, forever. An LLM may help\n  write a tool once; the tool must then stand on its own.\n- **Validate accessibility, design, and functionality requirements** — checks\n  a single maintainer could not perform by hand across every language, version,\n  and browser.\n\nThe most daunting recurring problem this addresses is translation upkeep.\nEvery version-specific translation must:\n\n1. exist — or the site must give clear guidance for contributing one;\n2. be accurate and consistent with the original English guidelines, while\n   remaining understandable in its own language and culture.\n\nTooling helps check these. Humans decide them.\n\n## Writing and content\n\nThe content is held to `docs/tone-and-voice.md`. In short: write plainly,\nlead with the point, don't gatekeep, and prefer wording a non-native reader\ncan understand on the first pass and a translator can translate rather than\nrephrase. This applies to site content, and it is a good default for\ndocumentation and commit messages too.\n\nGuidelines on the site should explain their reasoning. A reader should be able\nto disagree intelligently with any recommendation we make, because we told\nthem why we make it.\n"},"files":{"AGENTS.md":"# Working on Keep a Changelog\n\nThis file explains why the project is built the way it is. When a change\nconflicts with these principles, the principles win.\n\nHow-to guidance — setup, common tasks, and the translation workflow — lives\nexclusively in [CONTRIBUTING.md](CONTRIBUTING.md). Do not repeat it here;\npoint to it instead.\n\n## What this project is\n\nKeep a Changelog is a set of mindful guidelines for human-centered change\ncommunication. It is not a spec for people to robotically validate against.\nThe site exists to help people communicate software changes to other humans,\nand every decision — in the writing and in the code — serves that goal.\n\nThe project has one maintainer, myriad contributors, and an oversized impact\non how software changes are communicated around the world. Most of that impact\ncomes from refusing easy tropes: we do not create or endorse specific tools,\nwe do not follow conventions blindly when they make little sense, and we do\nnot tell people what to do without regard for their specific contexts.\n\nApply the same judgment to the project itself. Favor simplicity, and when a\nrule needs to be strict, make the reasoning for that strictness clear.\n\n## Technical principles\n\n**No backend.** The site is static HTML, built once and served from GitHub\nPages. This keeps hosting simple, cheap, and durable. Do not introduce\nanything that requires a server, a database, or a build service beyond the\nexisting static build.\n\n**Ruby at heart, CLI-based.** This is a Ruby project (Middleman, Rake,\nMinitest), and every workflow runs from the command line ([CONTRIBUTING.md](CONTRIBUTING.md)\nlists the tasks). Prefer extending the existing Ruby and Rake tooling over\nadding new toolchains. Small exceptions exist where a tool is clearly the\nright one for the job (Playwright for cross-browser visual regression, a\nPython script for translation QA scoring) — they are dev-only and never part\nof the shipped site.\n\n**Boring is fine.** We do not need the most hyped language or framework.\nThe measure of a tool is whether the project is hindered without it, not\nwhether it is popular. Before proposing a migration or a new dependency, ask\nwhat problem it solves that the current setup cannot.\n\n**Translations are a first-class concern.** The site's incredible number of\ncommunity-created translations exists because translating and managing\nversions is deliberately accessible — to readers and to contributors. A\ntranslator can edit plain markup without understanding the build (the workflow\nis in [CONTRIBUTING.md](CONTRIBUTING.md)). Protect that: any change to how\npages are structured or versioned must remain easy for a non-programmer\ntranslator to follow.\n\n## How we use LLMs\n\nKeep a Changelog has one maintainer and myriad contributors. Keeping a free\nopen source project like this alive involves complicated logistics: dozens of\nlanguages, several spec versions in each, and a steady stream of contributions\nto review. That work does not happen without automation — and even automation\nrequires maintenance. LLMs help carry that load, within strict limits, because\nwasting resources is antithetical to what this project stands for.\n\nLLMs are **not** used to:\n\n- **Replace translators.** Translations are created and reviewed by people who\n  speak the language and know the culture. No model output can substitute for\n  that judgment.\n- **Decide what Keep a Changelog says.** The guidelines are human positions,\n  reasoned about and owned by humans.\n- **Spend tokens on needless features.** If a feature would not exist without\n  an LLM to justify it, it should not exist.\n\nLLMs **are** used to:\n\n- **Build reusable tools that do not need an LLM to run.** The translation\n  coverage lint, the semantic QA pipeline, and the version routing tests are\n  ordinary scripts anyone can run, offline, for free, forever. An LLM may help\n  write a tool once; the tool must then stand on its own.\n- **Validate accessibility, design, and functionality requirements** — checks\n  a single maintainer could not perform by hand across every language, version,\n  and browser.\n\nThe most daunting recurring problem this addresses is translation upkeep.\nEvery version-specific translation must:\n\n1. exist — or the site must give clear guidance for contributing one;\n2. be accurate and consistent with the original English guidelines, while\n   remaining understandable in its own language and culture.\n\nTooling helps check these. Humans decide them.\n\n## Writing and content\n\nThe content is held to `docs/tone-and-voice.md`. In short: write plainly,\nlead with the point, don't gatekeep, and prefer wording a non-native reader\ncan understand on the first pass and a translator can translate rather than\nrephrase. This applies to site content, and it is a good default for\ndocumentation and commit messages too.\n\nGuidelines on the site should explain their reasoning. A reader should be able\nto disagree intelligently with any recommendation we make, because we told\nthem why we make it.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Working on Keep a Changelog\n\nThis file explains why the project is built the way it is. When a change\nconflicts with these principles, the principles win.\n\nHow-to guidance — setup, common tasks, and the translation workflow — lives\nexclusively in [CONTRIBUTING.md](CONTRIBUTING.md). Do not repeat it here;\npoint to it instead.\n\n## What this project is\n\nKeep a Changelog is a set of mindful guidelines for human-centered change\ncommunication. It is not a spec for people to robotically validate against.\nThe site exists to help people communicate software changes to other humans,\nand every decision — in the writing and in the code — serves that goal.\n\nThe project has one maintainer, myriad contributors, and an oversized impact\non how software changes are communicated around the world. Most of that impact\ncomes from refusing easy tropes: we do not create or endorse specific tools,\nwe do not follow conventions blindly when they make little sense, and we do\nnot tell people what to do without regard for their specific contexts.\n\nApply the same judgment to the project itself. Favor simplicity, and when a\nrule needs to be strict, make the reasoning for that strictness clear.\n\n## Technical principles\n\n**No backend.** The site is static HTML, built once and served from GitHub\nPages. This keeps hosting simple, cheap, and durable. Do not introduce\nanything that requires a server, a database, or a build service beyond the\nexisting static build.\n\n**Ruby at heart, CLI-based.** This is a Ruby project (Middleman, Rake,\nMinitest), and every workflow runs from the command line ([CONTRIBUTING.md](CONTRIBUTING.md)\nlists the tasks). Prefer extending the existing Ruby and Rake tooling over\nadding new toolchains. Small exceptions exist where a tool is clearly the\nright one for the job (Playwright for cross-browser visual regression, a\nPython script for translation QA scoring) — they are dev-only and never part\nof the shipped site.\n\n**Boring is fine.** We do not need the most hyped language or framework.\nThe measure of a tool is whether the project is hindered without it, not\nwhether it is popular. Before proposing a migration or a new dependency, ask\nwhat problem it solves that the current setup cannot.\n\n**Translations are a first-class concern.** The site's incredible number of\ncommunity-created translations exists because translating and managing\nversions is deliberately accessible — to readers and to contributors. A\ntranslator can edit plain markup without understanding the build (the workflow\nis in [CONTRIBUTING.md](CONTRIBUTING.md)). Protect that: any change to how\npages are structured or versioned must remain easy for a non-programmer\ntranslator to follow.\n\n## How we use LLMs\n\nKeep a Changelog has one maintainer and myriad contributors. Keeping a free\nopen source project like this alive involves complicated logistics: dozens of\nlanguages, several spec versions in each, and a steady stream of contributions\nto review. That work does not happen without automation — and even automation\nrequires maintenance. LLMs help carry that load, within strict limits, because\nwasting resources is antithetical to what this project stands for.\n\nLLMs are **not** used to:\n\n- **Replace translators.** Translations are created and reviewed by people who\n  speak the language and know the culture. No model output can substitute for\n  that judgment.\n- **Decide what Keep a Changelog says.** The guidelines are human positions,\n  reasoned about and owned by humans.\n- **Spend tokens on needless features.** If a feature would not exist without\n  an LLM to justify it, it should not exist.\n\nLLMs **are** used to:\n\n- **Build reusable tools that do not need an LLM to run.** The translation\n  coverage lint, the semantic QA pipeline, and the version routing tests are\n  ordinary scripts anyone can run, offline, for free, forever. An LLM may help\n  write a tool once; the tool must then stand on its own.\n- **Validate accessibility, design, and functionality requirements** — checks\n  a single maintainer could not perform by hand across every language, version,\n  and browser.\n\nThe most daunting recurring problem this addresses is translation upkeep.\nEvery version-specific translation must:\n\n1. exist — or the site must give clear guidance for contributing one;\n2. be accurate and consistent with the original English guidelines, while\n   remaining understandable in its own language and culture.\n\nTooling helps check these. Humans decide them.\n\n## Writing and content\n\nThe content is held to `docs/tone-and-voice.md`. In short: write plainly,\nlead with the point, don't gatekeep, and prefer wording a non-native reader\ncan understand on the first pass and a translator can translate rather than\nrephrase. This applies to site content, and it is a good default for\ndocumentation and commit messages too.\n\nGuidelines on the site should explain their reasoning. A reader should be able\nto disagree intelligently with any recommendation we make, because we told\nthem why we make it.\n","category":"root","tokens":1249}]}