diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 3fdc6a85..3a8d34c5 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -91,7 +91,7 @@ jobs:
const fname = '${{ env.POLYBAR_ARCHIVE }}'
const url = '${{ steps.upload_archive.outputs.browser_download_url }}'
const hash = '${{ env.SHA256SUM }}'
- let body = "### Download:\n\n"
+ let body = "## Download:\n\n"
body += `[${fname}](${url}) (**sha256**: \`${hash}\`)\n\n`
body += process.env.RELEASE_BODY;
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 00000000..fea91a44
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,39 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+Each release should have the following subsections, if entries exist, in the
+given order: `Breaking`, `Build`, `Deprecated`, `Removed`, `Added`, `Changed`,
+`Fixed`, `Security`.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+### Added
+- Warn states for the cpu, memory, fs, and battery modules.
+ ([`#570`](https://github.com/polybar/polybar/issues/570),
+ [`#956`](https://github.com/polybar/polybar/issues/956),
+ [`#1871`](https://github.com/polybar/polybar/issues/1871),
+ [`#2141`](https://github.com/polybar/polybar/issues/2141))
+ - `internal/battery`: `format-low`, `label-low`, `animation-low`, `low-at =
+ 10`.
+ - `internal/cpu`: `format-warn`, `label-warn`, `warn-percentage = 80`
+ - `internal/fs`: `format-warn`, `label-warn`, `warn-percentage = 90`
+ - `internal/memory`: `format-warn`, `label-warn`, `warn-percentage = 90`
+- Per-corner corner radius with `radius-{bottom,top}-{left,right}`
+ ([`#2294`](https://github.com/polybar/polybar/issues/2294))
+- `internal/network`: `speed-unit = B/s` can be used to customize how network
+ speeds are displayed.
+
+### Changed
+- Slight changes to the value ranges the different ramp levels are responsible
+ for in the cpu, memory, fs, and battery modules. The first and last level are
+ only used for everything at or below and at and above the edges of the value
+ range, respectively. The other levels are evenly distributed over the value
+ range as before.
+- `custom/script`: `interval` now defaults to 0 if `tail = true` as per the
+ documentation.
+- `internal/network`:
+ - Increased precision for upload and download speeds: 0 decimal places for
+ KB/s (as before), 1 for MB/s and 2 for GB/s.
+
+[Unreleased]: https://github.com/polybar/polybar/compare/3.5.2...HEAD
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 90c86726..aa1eeaea 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -100,6 +100,27 @@ wiki for more information.
Also don't hesitate to ask for help, testing isn't that mature in polybar yet
and some things may be harder/impossible to test right now.
+### Changelog
+
+If your PR introduces notable changes to polybar, please add them to the top of
+the `Unreleased` section in the `CHANGELOG.md` file at the root of this
+repository.
+Notable changes are any user-visible changes, like bug fixes, new config
+options, changes to the build, etc., but not, for example, code cleanup that
+doesn't change polybar's behavior or minor documentation changes.
+One thing that also should not be added to the changelog are bugfixes for
+unreleased features.
+
+Also add a reference to all issues that this PR addresses in parentheses behind
+the changelog entry:
+
+```
+[`#1234`](https://github.com/polybar/polybar/issues/1234)
+```
+
+If you are unsure whether something is a notable change, just add it to the
+changelog and we can determine whether it is a notable change when reviewing.
+
### Documentation
Right now, documentation for polybar lives in two places: The GitHub wiki and
diff --git a/doc/dev/release-workflow.rst b/doc/dev/release-workflow.rst
index 54e21146..59daa5ee 100644
--- a/doc/dev/release-workflow.rst
+++ b/doc/dev/release-workflow.rst
@@ -144,17 +144,43 @@ The release commit needs to update the version number in:
* ``version.txt``
-The commit message contains the `Changelog`_ for this release.
+The release commit must also finalize the `Changelog`_ for this release.
Changelog
~~~~~~~~~
-Each release should come with a changelog briefly explaining what has changed
-for the user. It should generally be separated into 'Deprecations', 'Features',
-and 'Fixes', with 'Breaking Changes' listed separately at the top.
+The ``CHANGELOG.md`` file at the root of the repo should already contain all the
+changes for the upcoming release in a format based on
+`keep a changelog `_.
+For each release those changes should be checked to make sure we did not miss
+anything.
-See `old releases `_ for how to
-format the changelog.
+For all releases, a new section of the following form should be created below
+the ``Unreleased`` section:
+
+.. code-block::
+
+ ## [X.Y.Z] - YYYY-MM-DD
+
+In addition, the reference link for the release should be added and the
+reference link for the unreleased section should be updated at the bottom of the
+document:
+
+.. code-block::
+
+ [Unreleased]: https://github.com/polybar/polybar/compare/X.Y.Z...HEAD
+ [X.Y.Z]: https://github.com/polybar/polybar/releases/tag/X.Y.Z
+
+Since the release tag doesn't exist yet, both of these links will be invalid
+until the release is published.
+
+All changes from the ``Unreleased`` section that apply to this release should be
+moved into the new release section.
+For regular releases this is generally the entire ``Unreleased`` section, while
+for patch releases it will only be a few entries.
+
+The contents of the release section can be copied into the draft release in
+GitHub's release tool with a heading named ``## Changelog``.
Since major releases generally break backwards compatibility in some way, their
changelog should also prominently feature precisely what breaking changes were
@@ -179,7 +205,6 @@ After-Release Checklist
* Create a PR that updates the AUR ``PKGBUILD`` files for the ``polybar`` and
``polybar-git`` packages (push after the release archive is uploaded).
-
Deprecations
~~~~~~~~~~~~