Adopt "keep a changelog" (#2308)

* Adopt keep a changelog

Ref: https://keepachangelog.com/en/1.0.0/

* Add changelog to release and contributing docs

* Use H2 for automatically added Download section

The individual changelog subsections use H3 and the changelog section
uses H2, so the Download section should use the same heading

* Add already present changes to changelog

* Mention changelog issue references in CONTRIBUTING.md

.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;
 

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

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

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 <https://keepachangelog.com/en/1.0.0/>`_.
+For each release those changes should be checked to make sure we did not miss
+anything.
 
-See `old releases <https://github.com/polybar/polybar/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
 ~~~~~~~~~~~~