Skip to content

Document changelog best practices #2169

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

Document changelog best practices #2169

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 35 additions & 2 deletions changelog/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,39 @@ somewhat manageable:
* Create a changelog file: `touch $(date --iso-8601=seconds | tr : _)_my_change_message`
* We collect these files for each release and put their messages in
`CHANGELOG.md`. The files are subsequently deleted.
* Messages should be valid Markdown

I've added an example to the commit introducing this change.
A changelog file can contain multiple entries. Each entry starts with a tag
word from the list below, followed by one or more lines of text in Markdown
format. An entry should mention the GitHub PR that introduces the change or the
GitHub issue that the change fixes.

Changelog entries should be understandable as a stand-alone text; it should give
the reader an overview of the change without needing to consult more
documentation, but it can refer to other documentation for further information.
A Changelog entry is allowed to be verbose, but it need not duplicate
documentation; a link to further documentation is often enough.

Example:

```
ADDED: Commodo eros. Suspendisse tincidunt mi vel metus. [#1234](https://github.com/clash-lang/clash-compiler/pull/1234)
FIXED: Facilisis neque. Nulla mattis odio vitae tortor. [#1234](https://github.com/clash-lang/clash-compiler/issues/1234)
Comment on lines +24 to +25
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tend to rewrite these quite often because the changelogs included are often along these lines:

Don't render extended identifiers in SDC files

This is fine for commit messages, but for the changelog I'd like to see:

Clash no longer escapes extended identifiers when rendering SDC files, this improves blabla

So I think it would be nice to replace the lorum ipsum with some examples.

```

The tags we use are:
* ADDED:
* FIXED:
* CHANGED:
* DEPRECATED:
* REMOVED:
* INTERNAL NEW:
* INTERNAL FIX:
* INTERNAL CHANGE:
* DOCUMENTATION:
(meaning something that only affects documentation, not code)
Comment on lines +29 to +38
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✔️


Usually, the name of the section in the CHANGELOG is equal to the tag;
the exceptions are:
* INTERNAL NEW: Listed in a CHANGELOG section named _New internal features:_
* INTERNAL FIX: Listed in a CHANGELOG section named _Internal fixes:_
* INTERNAL CHANGE: Listed in a CHANGELOG section named _Internal changes:_