1Release Workflow 2================ 3 4We try to follow `Semantic Versioning <https://semver.org/>`_ in this project. 5Patch releases (e.g. ``3.3.X``) contain only bug fixes. Minor releases (e.g. 6``3.X.0``) can have backwards-compatible features. And major releases ( 7``X.0.0``) can introduce incompatible changes. 8 9.. note:: 10 11 This document replaces the "`Release Guidelines 12 <https://github.com/polybar/polybar/wiki/Release-Guidelines>`_" on the wiki 13 that we used between 3.2.0 and 3.4.3. Starting with 3.5.0, we will follow 14 the workflow described here to publish releases. 15 16Polybar uses the `OneFlow 17<https://www.endoflineblog.com/oneflow-a-git-branching-model-and-workflow>`_ 18branching model for publishing new releases and introducing hotfixes. 19 20The way we accept code from contributors does not change: Contributors fork 21polybar, commit their changes to a new branch and open a PR to get that branch 22merged. 23After reviewing and approving the changes, a maintainer "merges" the PR. 24"Merging" is done in the GitHub UI by either rebasing or squashing the 25changes. 26Regular merging is disabled because we do not want merge a merge commit for 27every PR. 28 29This document is mainly concerned with how to properly release a new version of 30polybar. 31For that reason this might not be of interest to you, if you are not a 32maintainer, but feel free to read on anyway. 33 34Drafting a new Release 35---------------------- 36 37There a two processes for how to draft a new release. The process for major and 38minor versions is the same as they both are "regular" releases. 39Patch releases are triggered by bugfixes that cannot wait until the next regular 40release and have a slightly different workflow. 41 42Regular Releases (Major, Minor) 43~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 44 45Regular releases are created once we find that ``master`` is in a stable state 46and that there are enough new features to justify a new release. 47A release branch ``release/X.Y.0`` is branched off of a commit on ``master`` 48that contains all the features we want in the release, this branch is pushed to 49the official repository. 50For example for version ``3.5.0`` the branch ``release/3.5.0`` would be created: 51 52.. code-block:: shell 53 54 git checkout -b release/3.5.0 <commit> 55 56The release branch should typically only exist for at most a few days. 57 58Hotfix Releases (Patch) 59~~~~~~~~~~~~~~~~~~~~~~~ 60 61A hotfix release is created whenever we receive a fix for a bug that we believe 62should be released immediately instead of it only being part of the next regular 63release. 64Generally any bugfix qualifies, but it is up to the maintainers to decide 65whether a hotfix release should be created. 66 67The hotfix release branch ``hotfix/X.Y.Z`` is created by branching off at the 68previous release tag (``X.Y.Z-1``). 69For example, if the latest version is ``3.5.2``, the next hotfix will be on 70branch ``hotfix/3.5.3``: 71 72.. code-block:: shell 73 74 git checkout -b hotfix/3.5.3 3.5.2 75 76Since the PRs for such bugfixes are often not created by maintainers, they will 77often not be based on the latest release tag, but just be branched off 78``master`` because contributors don't necessarily know about this branching 79model and also may well not know whether a hotfix will be created for a certain 80bugfix. 81 82.. TODO create contributor page that describes where to branch off. And link to 83 that page. 84 85In case a PR containing a bugfix that is destined for a patch release is not 86branched off the previous release, a maintainer creates the proper release 87branch and cherry-picks the bugfix commits. 88 89.. note:: 90 91 Alternatively, the contributor can also ``git rebase --onto`` to base the 92 branch off the previous release tag. However, in most cases it makes sense for 93 a maintainer to create the release branch since they will also need to add a 94 `Release Commit`_ to it. 95 96Once the release branch is created and contains the right commits, the 97maintainer should follow `Publishing a new Release`_ to finish this patch 98release. 99 100If multiple bugfixes are submitted in close succession, they can all be 101cherry-picked onto the same patch release branch to not create many individual 102release with only a single fix. 103The maintainer can also decide to leave the release branch for this patch 104release open for a week in order to possibly combine multiple bugfixes into a 105single release. 106 107Publishing a new Release 108------------------------ 109 110The process for publishing a release is the same for all release types. It goes 111as follows: 112 113* A `Release commit`_ is added to the tip of the release branch. 114* A draft PR is opened for the release branch. This PR MUST NOT be merged in 115 GitHub's interface, it is only here for review, merging happens at the 116 commandline. 117* After approval, the GitHub release publishing tool is used to publish the 118 release and tag the tip of the release branch (the release commit). 119* After the tag is created, the release branch is manually merged into 120 ``master``. 121 Here it is vitally important that the history of the release branch does not 122 change and so we use ``git merge``. We do it manually because using ``git 123 merge`` is disabled on PRs. 124 125.. code-block:: shell 126 127 git checkout master 128 git merge <release-branch> 129 git push origin 130 131* After the tag is created, the release branch can be deleted with ``git push 132 origin :<release-branch>``. 133* Work through the `After-Release Checklist`_. 134 135Here ``<release-branch>`` is either a ``release/X.Y.0`` branch or a 136``hotfix/X.Y.Z`` branch. 137 138Release Commit 139~~~~~~~~~~~~~~ 140 141When merging, a release commit must be at the tip of the release branch. 142 143The release commit needs to update the version number in: 144 145* ``version.txt`` 146 147The commit message contains the `Changelog`_ for this release. 148 149Changelog 150~~~~~~~~~ 151 152Each release should come with a changelog briefly explaining what has changed 153for the user. It should generally be separated into 'Deprecations', 'Features', 154and 'Fixes', with 'Breaking Changes' listed separately at the top. 155 156See `old releases <https://github.com/polybar/polybar/releases>`_ for how to 157format the changelog. 158 159Since major releases generally break backwards compatibility in some way, their 160changelog should also prominently feature precisely what breaking changes were 161introduced. If suitable, maybe even separate documentation dedicated to the 162migration should be written. 163 164After-Release Checklist 165~~~~~~~~~~~~~~~~~~~~~~~ 166 167* Make sure all the new functionality is documented on the wiki 168* Mark deprecated features appropriately (see `Deprecations`_) 169* Remove all unreleased notes from the wiki (not for patch releases) 170* Inform packagers of new release in `#1971 171 <https://github.com/polybar/polybar/issues/1971>`_. Mention any dependency 172 changes and any changes to the build workflow. Also mention any new files are 173 created by the installation. 174* Create a source archive named ``polybar-<version>.tar``. 175 The repository contains a script that automates this: 176 177.. code-block:: shell 178 179 ./common/release-archive.sh <version> 180 181* Update the github release with a download section that contains a link to 182 ``polybar-<version>.tar`` and its sha256. 183* Create a PR that updates the AUR ``PKGBUILD`` files for the ``polybar`` and 184 ``polybar-git`` packages (push after the ``.tar`` file was created). 185 186 187Deprecations 188~~~~~~~~~~~~ 189 190If any publicly facing part of polybar is being deprecated, it should be marked 191as such in the code, through warnings/errors in the log, and by comments in the 192wiki. Every deprecated functionality is kept until the next major release and 193removed there, unless it has not been deprecated in a minor release before. 194