From d63bf294b737d5d93f7452071f024ea87c1a1733 Mon Sep 17 00:00:00 2001 From: Patrick Ziegler Date: Wed, 16 Dec 2020 16:04:10 +0100 Subject: [PATCH] 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 | 2 +- CHANGELOG.md | 39 +++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 21 +++++++++++++++++++ doc/dev/release-workflow.rst | 39 ++++++++++++++++++++++++++++------- 4 files changed, 93 insertions(+), 8 deletions(-) create mode 100644 CHANGELOG.md 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 ~~~~~~~~~~~~