From e187fa4bc81b892f8243d588608b8e2f3bddcb9a Mon Sep 17 00:00:00 2001 From: Kyle Altendorf Date: Sun, 12 Mar 2023 09:32:06 -0400 Subject: [PATCH 1/3] encourage expression of what interface the semantic versioning covers > Mention whether you follow Semantic Versioning and what interfaces it covers. https://github.com/olivierlacan/keep-a-changelog/discussions/536 --- source/en/1.2.0/index.html.haml | 316 ++++++++++++++++++++++++++++++++ 1 file changed, 316 insertions(+) create mode 100644 source/en/1.2.0/index.html.haml diff --git a/source/en/1.2.0/index.html.haml b/source/en/1.2.0/index.html.haml new file mode 100644 index 00000000..8af1a177 --- /dev/null +++ b/source/en/1.2.0/index.html.haml @@ -0,0 +1,316 @@ +--- +description: Keep a Changelog +title: Keep a Changelog +language: en +version: 1.2.0 +--- +.header + .title + %h1 Keep a Changelog + %h2 Don’t let your friends dump git logs into changelogs. + + = link_to data.links.changelog do + Version + %strong= current_page.metadata[:page][:version] + + %pre.changelog{ lang: "en" }= File.read("CHANGELOG.md") + +.answers + %h3#what + %a.anchor{ href: "#what", aria_hidden: "true" } + What is a changelog? + + %p + A changelog is a file which contains a curated, chronologically + ordered list of notable changes for each version of a project. + + %h3#why + %a.anchor{ href: "#why", aria_hidden: "true" } + Why keep a changelog? + + %p + To make it easier for users and contributors to see precisely what + notable changes have been made between each release (or version) of + the project. + + %h3#who + %a.anchor{ href: "#who", aria_hidden: "true" } + Who needs a changelog? + + %p + People do. Whether consumers or developers, the end users of + software are human beings who care about what's in the software. When + the software changes, people want to know why and how. + +.good-practices + %h3#how + %a.anchor{ href: "#how", aria_hidden: "true" } + How do I make a good changelog? + + %h4#principles + %a.anchor{ href: "#principles", aria_hidden: "true" } + Guiding Principles + + %ul + %li + Changelogs are for humans, not machines. + %li + There should be an entry for every single version. + %li + The same types of changes should be grouped. + %li + Versions and sections should be linkable. + %li + The latest version comes first. + %li + The release date of each version is displayed. + %li + Mention whether you follow #{link_to "Semantic Versioning", data.links.semver} and what interfaces it covers. + + %a.anchor{ href: "#types", aria_hidden: "true" } + %h4#types Types of changes + + %ul + %li + %code Added + for new features. + %li + %code Changed + for changes in existing functionality. + %li + %code Deprecated + for soon-to-be removed features. + %li + %code Removed + for now removed features. + %li + %code Fixed + for any bug fixes. + %li + %code Security + in case of vulnerabilities. + +.effort + + %h3#effort + %a.anchor{ href: "#effort", aria_hidden: "true" } + How can I reduce the effort required to maintain a changelog? + + %p + Keep an Unreleased section at the top to track upcoming + changes. + + %p This serves two purposes: + + %ul + %li + People can see what changes they might expect in upcoming releases + %li + At release time, you can move the Unreleased section + changes into a new release version section. + +.bad-practices + %h3#bad-practices + %a.anchor{ href: "#bad-practices", aria_hidden: "true" } + Can changelogs be bad? + + %p Yes. Here are a few ways they can be less than useful. + + %h4#log-diffs + %a.anchor{ href: "#log-diffs", aria_hidden: "true" } + Commit log diffs + + %p + Using commit log diffs as changelogs is a bad idea: they're full of + noise. Things like merge commits, commits with obscure titles, + documentation changes, etc. + + %p + The purpose of a commit is to document a step in the evolution of + the source code. Some projects clean up commits, some don't. + + %p + The purpose of a changelog entry is to document the noteworthy + difference, often across multiple commits, to communicate them + clearly to end users. + + %h4#ignoring-deprecations + %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" } + Ignoring Deprecations + + %p + When people upgrade from one version to another, it should be + painfully clear when something will break. It should be possible to + upgrade to a version that lists deprecations, remove what's + deprecated, then upgrade to the version where the deprecations + become removals. + + %p + If you do nothing else, list deprecations, removals, and any + breaking changes in your changelog. + + + %h4#confusing-dates + %a.anchor{ href: "#confusing-dates", aria_hidden: "true" } + Confusing Dates + + %p + Regional date formats vary throughout the world and it's often + difficult to find a human-friendly date format that feels intuitive + to everyone. The advantage of dates formatted like + 2017-07-17 is that they follow the order of largest to + smallest units: year, month, and day. This format also doesn't + overlap in ambiguous ways with other date formats, unlike some + regional formats that switch the position of month and day numbers. + These reasons, and the fact this date format is an + #{link_to "ISO standard", data.links.isodate}, are why it is the recommended date + format for changelog entries. + + %h4#inconsistent-changes + %a.anchor{ href: "#inconsistent-changes", aria_hidden: "true" } + Inconsistent Changes + + %p + A changelog which only mentions some of the changes can be as dangerous + as not having a changelog. While many of the changes may not be + relevant - for instance, removing a single whitespace may not need + to be recorded in all instances - any important changes should be + mentioned in the changelog. By inconsistently applying changes, + your users may mistakenly think that the changelog is the single source + of truth. It ought to be. With great power comes great responsibility - + having a good changelog means having a consistently updated changelog. + + %aside + There’s more. Help me collect these antipatterns by + = link_to "opening an issue", data.links.issue + or a pull request. + +.frequently-asked-questions + %h3#frequently-asked-questions + %a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" } + Frequently Asked Questions + + %h4#standard + %a.anchor{ href: "#standard", aria_hidden: "true" } + Is there a standard changelog format? + + %p + Not really. There's the #{link_to "GNU changelog style guide", data.links.gnustyle}, + or the #{link_to "two-paragraph-long GNU NEWS file", data.links.gnunews} + "guideline". Both are inadequate or insufficient. + + %p + This project aims to be + = link_to "a better changelog convention.", data.links.changelog + It comes from observing good practices in the open source + community and gathering them. + + %p + Healthy criticism, discussion and suggestions for improvements + = link_to "are welcome.", data.links.issue + + + %h4#filename + %a.anchor{ href: "#filename", aria_hidden: "true" } + What should the changelog file be named? + + %p + Call it CHANGELOG.md. Some projects use + HISTORY, NEWS or RELEASES. + + %p + While it's easy to think that the name of your changelog file + doesn't matter that much, why make it harder for your end users to + consistently find notable changes? + + %h4#github-releases + %a.anchor{ href: "#github-releases", aria_hidden: "true" } + What about GitHub Releases? + + %p + It's a great initiative. #{link_to "Releases", data.links.github_releases} can be used to + turn simple git tags (for example a tag named v1.0.0) + into rich release notes by manually adding release notes or it can + pull annotated git tag messages and turn them into notes. + + %p + GitHub Releases create a non-portable changelog that can only be + displayed to users within the context of GitHub. It's possible to + make them look very much like the Keep a Changelog format, but it + tends to be a bit more involved. + + %p + The current version of GitHub releases is also arguably not very + discoverable by end-users, unlike the typical uppercase files + (README, CONTRIBUTING, etc.). Another + minor issue is that the interface doesn't currently offer links to + commit logs between each release. + + %h4#automatic + %a.anchor{ href: "#automatic", aria_hidden: "true" } + Can changelogs be automatically parsed? + + %p + It’s difficult, because people follow wildly different formats and + file names. + + %p + #{link_to "Vandamme", data.links.vandamme} is a Ruby gem created by the + Gemnasium team and which parses many (but + not all) open source project changelogs. + + + %h4#yanked + %a.anchor{ href: "#yanked", aria_hidden: "true" } + What about yanked releases? + + %p + Yanked releases are versions that had to be pulled because of a + serious bug or security issue. Often these versions don't even + appear in change logs. They should. This is how you should display + them: + + %p ## [0.0.5] - 2014-12-13 [YANKED] + + %p + The [YANKED] tag is loud for a reason. It's important + for people to notice it. Since it's surrounded by brackets it's also + easier to parse programmatically. + + + %h4#rewrite + %a.anchor{ href: "#rewrite", aria_hidden: "true" } + Should you ever rewrite a changelog? + + %p + Sure. There are always good reasons to improve a changelog. I + regularly open pull requests to add missing releases to open source + projects with unmaintained changelogs. + + %p + It's also possible you may discover that you forgot to address a + breaking change in the notes for a version. It's obviously important + for you to update your changelog in this case. + + + %h4#contribute + %a.anchor{ href: "#contribute", aria_hidden: "true" } + How can I contribute? + + %p + This document is not the truth; it’s my carefully + considered opinion, along with information and examples I gathered. + + %p + This is because I want our community to reach a consensus. I believe + the discussion is as important as the end result. + + %p + So please #{link_to "pitch in", data.links.repo}. + +.press + %h3 Conversations + %p + I went on #{link_to "The Changelog podcast", data.links.thechangelog} + to talk about why maintainers and contributors should care about changelogs, + and also about the motivations behind this project. From d997a2426a84d57cda94cbed338e5db6a0094c11 Mon Sep 17 00:00:00 2001 From: Kyle Altendorf Date: Sun, 12 Mar 2023 09:56:24 -0400 Subject: [PATCH 2/3] add a semantic versioning faq entry --- source/en/1.2.0/index.html.haml | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/source/en/1.2.0/index.html.haml b/source/en/1.2.0/index.html.haml index 8af1a177..01dcb6c7 100644 --- a/source/en/1.2.0/index.html.haml +++ b/source/en/1.2.0/index.html.haml @@ -260,6 +260,21 @@ version: 1.2.0 not all) open source project changelogs. + %h4#semver + %a.anchor{ href: "#automatic", aria_hidden: "true" } + What should be said about Semantic Versioning coverage? + + %p + It is valuable to document both what parts of the project are following + the rules of #{link_to "Semantic Versioning", data.links.semver}, as + well as what parts are not. A project may provide programming language + native APIs, CLIs, RPCs, network protocols, file formats, or even have + compatibility concerns around the data transferred through any of those. + + %p + Making this clear to users of a project helps them understand how to + interpret the versions of the project and the sections of the changelog. + %h4#yanked %a.anchor{ href: "#yanked", aria_hidden: "true" } What about yanked releases? From bc3e7fbbe374faecb8a30ce1eae29d4d5abc8e27 Mon Sep 17 00:00:00 2001 From: Kyle Altendorf Date: Sun, 12 Mar 2023 09:57:37 -0400 Subject: [PATCH 3/3] correct href --- source/en/1.2.0/index.html.haml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/en/1.2.0/index.html.haml b/source/en/1.2.0/index.html.haml index 01dcb6c7..602746b5 100644 --- a/source/en/1.2.0/index.html.haml +++ b/source/en/1.2.0/index.html.haml @@ -261,7 +261,7 @@ version: 1.2.0 %h4#semver - %a.anchor{ href: "#automatic", aria_hidden: "true" } + %a.anchor{ href: "#semver", aria_hidden: "true" } What should be said about Semantic Versioning coverage? %p