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
This commit is contained in:
Patrick Ziegler 2020-12-16 16:04:10 +01:00 committed by GitHub
parent 680bb2d5e4
commit d63bf294b7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 93 additions and 8 deletions

View File

@ -91,7 +91,7 @@ jobs:
const fname = '${{ env.POLYBAR_ARCHIVE }}' const fname = '${{ env.POLYBAR_ARCHIVE }}'
const url = '${{ steps.upload_archive.outputs.browser_download_url }}' const url = '${{ steps.upload_archive.outputs.browser_download_url }}'
const hash = '${{ env.SHA256SUM }}' const hash = '${{ env.SHA256SUM }}'
let body = "### Download:\n\n" let body = "## Download:\n\n"
body += `[${fname}](${url}) (**sha256**: \`${hash}\`)\n\n` body += `[${fname}](${url}) (**sha256**: \`${hash}\`)\n\n`
body += process.env.RELEASE_BODY; body += process.env.RELEASE_BODY;

39
CHANGELOG.md Normal file
View File

@ -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

View File

@ -100,6 +100,27 @@ wiki for more information.
Also don't hesitate to ask for help, testing isn't that mature in polybar yet 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. 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 ### Documentation
Right now, documentation for polybar lives in two places: The GitHub wiki and Right now, documentation for polybar lives in two places: The GitHub wiki and

View File

@ -144,17 +144,43 @@ The release commit needs to update the version number in:
* ``version.txt`` * ``version.txt``
The commit message contains the `Changelog`_ for this release. The release commit must also finalize the `Changelog`_ for this release.
Changelog Changelog
~~~~~~~~~ ~~~~~~~~~
Each release should come with a changelog briefly explaining what has changed The ``CHANGELOG.md`` file at the root of the repo should already contain all the
for the user. It should generally be separated into 'Deprecations', 'Features', changes for the upcoming release in a format based on
and 'Fixes', with 'Breaking Changes' listed separately at the top. `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 For all releases, a new section of the following form should be created below
format the changelog. 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 Since major releases generally break backwards compatibility in some way, their
changelog should also prominently feature precisely what breaking changes were 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 * Create a PR that updates the AUR ``PKGBUILD`` files for the ``polybar`` and
``polybar-git`` packages (push after the release archive is uploaded). ``polybar-git`` packages (push after the release archive is uploaded).
Deprecations Deprecations
~~~~~~~~~~~~ ~~~~~~~~~~~~