tyler.durden/keep-a-changelog
1
0
Fork 0
mirror of https://github.com/olivierlacan/keep-a-changelog.git synced 2025-07-31 01:34:18 +02:00
Code Issues Packages Projects Releases Wiki Activity

Canonical changelogs over releae post

Browse Source 
As discussed in a recent [PR][1], people should treat their 
changelogs as canonical sources given their portability. 

Release posts can easily be created manually or automatically
since the Keep a Changelog format is easy to parse for both 
humans and machines.

[1]: https://github.com/olivierlacan/keep-a-changelog/pull/629#issuecomment-2766514005
This commit is contained in:
Olivier Lacan 2025-03-31 08:20:00 -07:00 committed by GitHub
parent b136e5a1d1
commit d93bdfde52
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 16 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
source/en/2.0.0/index.html.haml
View File

@ -258,23 +258,26 @@ version: 1.1.0
export. Rather than be pedantic about the common usage of the word
"changelog", it seems more fruitful to work toward improving them.
%h4#github-releases
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
What about GitHub Releases?
%h4#releases
%a.anchor{ href: "#releases", aria_hidden: "true" }
What about Releases?
%p.updated
It has come a long way. When #{link_to "Releases", data.links.github_releases}
first came out, it was quite limited. It's now a much more prominent feature
that supports converting git tags (for example <code>v1.0.0</code>)
into rich release notes by either retrieving the git tag message or typing
specific release notes that will only be displayed on GitHub.
Code hosting platform offer ways to publish release posts. Nowadays
many projects communicate about version releases using these posts. Posts
can be created from with version-specific git tags.
%p.updated
An important caveat of GitHub Releases is that it can easily entice
maintainers to create non-portable information about project changes.
While release notes written for GitHub will be shown to users there, they're
not kept inside the git history like a changelog file stored within the repo
would be.
The value of these release posts is limited. They often encourage
maintainers to create information about project changes that is not portable
across code hosting platforms. When release notes are published exclusively
in these posts, they're not kept in version history unlike like a changelog
text file stored in the repository.
%p.update
It's best to focus on changelog text files first and either derive these
individual release posts manually or use tools to create release posts
when a new version is added to the changelog.
%h4#automatic
%a.anchor{ href: "#automatic", aria_hidden: "true" }