mirror of
https://github.com/polybar/polybar.git
synced 2024-11-11 13:50:56 -05:00
doc: Write new release workflow
We now use OneFlow [1] for releases 3.5.0 and onwards. Closes #1780 [1]: https://www.endoflineblog.com/oneflow-a-git-branching-model-and-workflow
This commit is contained in:
patrick96
Patrick Ziegler
parent
bb3647ff8d
commit
df15a4062a
2 changed files with 199 additions and 0 deletions
193
doc/dev/release-workflow.rst
Normal file
193
doc/dev/release-workflow.rst
Normal file
|
|
@ -0,0 +1,193 @@
|
|||
Release Workflow
|
||||
================
|
||||
|
||||
We try to follow `Semantic Versioning <https://semver.org/>`_ in this project.
|
||||
Patch releases (e.g. ``3.3.X``) contain only bug fixes. Minor releases (e.g.
|
||||
``3.X.0``) can have backwards-compatible features. And major releases (
|
||||
``X.0.0``) can introduce incompatible changes.
|
||||
|
||||
.. note::
|
||||
|
||||
This document replaces the "`Release Guidelines
|
||||
<https://github.com/polybar/polybar/wiki/Release-Guidelines>`_" on the wiki
|
||||
that we used between 3.2.0 and 3.4.3. Starting with 3.5.0, we will follow
|
||||
the workflow described here to publish releases.
|
||||
|
||||
Polybar uses the `OneFlow
|
||||
<https://www.endoflineblog.com/oneflow-a-git-branching-model-and-workflow>`_
|
||||
branching model for publishing new releases and introducing hotfixes.
|
||||
|
||||
The way we accept code from contributors does not change: Contributors fork
|
||||
polybar, commit their changes to a new branch and open a PR to get that branch
|
||||
merged.
|
||||
After reviewing and approving the changes, a maintainer "merges" the PR.
|
||||
"Merging" is done in the GitHub UI by either rebasing or squashing the
|
||||
changes.
|
||||
Regular merging is disabled because we do not want merge a merge commit for
|
||||
every PR.
|
||||
|
||||
This document is mainly concerned with how to properly release a new version of
|
||||
polybar.
|
||||
For that reason this might not be of interest to you, if you are not a
|
||||
maintainer, but feel free to read on anyway.
|
||||
|
||||
Drafting a new Release
|
||||
----------------------
|
||||
|
||||
There a two processes for how to draft a new release. The process for major and
|
||||
minor versions is the same as they both are "regular" releases.
|
||||
Patch releases are triggered by bugfixes that cannot wait until the next regular
|
||||
release and have a slightly different workflow.
|
||||
|
||||
Regular Releases (Major, Minor)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Regular releases are created once we find that ``master`` is in a stable state
|
||||
and that there are enough new features to justify a new release.
|
||||
A release branch ``release/X.Y.0`` is branched off of a commit on ``master``
|
||||
that contains all the features we want in the release, this branch is pushed to
|
||||
the official repository.
|
||||
For example for version ``3.5.0`` the branch ``release/3.5.0`` would be created:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
git checkout -b release/3.5.0 <commit>
|
||||
|
||||
The release branch should typically only exist for at most a few days.
|
||||
|
||||
Hotfix Releases (Patch)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
A hotfix release is created whenever we receive a fix for a bug that we believe
|
||||
should be released immediately instead of it only being part of the next regular
|
||||
release.
|
||||
Generally any bugfix qualifies, but it is up to the maintainers to decide
|
||||
whether a hotfix release should be created.
|
||||
|
||||
The hotfix release branch ``hotfix/X.Y.Z`` is created by branching off at the
|
||||
previous release tag (``X.Y.Z-1``).
|
||||
For example, if the latest version is ``3.5.2``, the next hotfix will be on
|
||||
branch ``hotfix/3.5.3``:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
git checkout -b hotfix/3.5.3 3.5.2
|
||||
|
||||
Since the PRs for such bugfixes are often not created by maintainers, they will
|
||||
often not be based on the latest release tag, but just be branched off
|
||||
``master`` because contributors don't necessarily know about this branching
|
||||
model and also may well not know whether a hotfix will be created for a certain
|
||||
bugfix.
|
||||
|
||||
.. TODO create contributor page that describes where to branch off. And link to
|
||||
that page.
|
||||
|
||||
In case a PR containing a bugfix that is destined for a patch release is not
|
||||
branched off the previous release, a maintainer creates the proper release
|
||||
branch and cherry-picks the bugfix commits.
|
||||
|
||||
.. note::
|
||||
|
||||
Alternatively, the contributor can also ``git rebase --onto`` to base the
|
||||
branch off the previous release tag. However, in most cases it makes sense for
|
||||
a maintainer to create the release branch since they will also need to add a
|
||||
`Release Commit`_ to it.
|
||||
|
||||
Once the release branch is created and contains the right commits, the
|
||||
maintainer should follow `Publishing a new Release`_ to finish this patch
|
||||
release.
|
||||
|
||||
If multiple bugfixes are submitted in close succession, they can all be
|
||||
cherry-picked onto the same patch release branch to not create many individual
|
||||
release with only a single fix.
|
||||
The maintainer can also decide to leave the release branch for this patch
|
||||
release open for a week in order to possibly combine multiple bugfixes into a
|
||||
single release.
|
||||
|
||||
Publishing a new Release
|
||||
------------------------
|
||||
|
||||
The process for publishing a release is the same for all release types. It goes
|
||||
as follows:
|
||||
|
||||
* A `Release commit`_ is added to the tip of the release branch.
|
||||
* A draft PR is opened for the release branch. This PR MUST NOT be merged in
|
||||
GitHub's interface, it is only here for review, merging happens at the
|
||||
commandline.
|
||||
* After approval, the GitHub release publishing tool is used to publish the
|
||||
release and tag the tip of the release branch (the release commit).
|
||||
* After the tag is created, the release branch is manually merged into
|
||||
``master``.
|
||||
Here it is vitally important that the history of the release branch does not
|
||||
change and so we use ``git merge``. We do it manually because using ``git
|
||||
merge`` is disabled on PRs.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
git checkout master
|
||||
git merge <release-branch>
|
||||
git push origin
|
||||
|
||||
* After the tag is created, the release branch can be deleted with ``git push
|
||||
origin :<release-branch>``.
|
||||
* Work through the `After-Release Checklist`_.
|
||||
|
||||
Here ``<release-branch>`` is either a ``release/X.Y.0`` branch or a
|
||||
``hotfix/X.Y.Z`` branch.
|
||||
|
||||
Release Commit
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
When merging, a release commit must be at the tip of the release branch.
|
||||
|
||||
The release commit needs to update the version number in:
|
||||
|
||||
* ``version.txt``
|
||||
|
||||
The commit message contains 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.
|
||||
|
||||
See `old releases <https://github.com/polybar/polybar/releases>`_ for how to
|
||||
format the changelog.
|
||||
|
||||
Since major releases generally break backwards compatibility in some way, their
|
||||
changelog should also prominently feature precisely what breaking changes were
|
||||
introduced. If suitable, maybe even separate documentation dedicated to the
|
||||
migration should be written.
|
||||
|
||||
After-Release Checklist
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* Make sure all the new functionality is documented on the wiki
|
||||
* Mark deprecated features appropriately (see `Deprecations`_)
|
||||
* Remove all unreleased notes from the wiki (not for patch releases)
|
||||
* Inform packagers of new release in `#1971
|
||||
<https://github.com/polybar/polybar/issues/1971>`_. Mention any dependency
|
||||
changes and any changes to the build workflow. Also mention any new files are
|
||||
created by the installation.
|
||||
* Create a source archive named ``polybar-<version>.tar``.
|
||||
The repository contains a script that automates this:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
./common/release-archive.sh <version>
|
||||
|
||||
* Update the github release with a download section that contains a link to
|
||||
``polybar-<version>.tar`` and its sha256.
|
||||
* Create a PR that updates the AUR ``PKGBUILD`` files for the ``polybar`` and
|
||||
``polybar-git`` packages (push after the ``.tar`` file was created).
|
||||
|
||||
|
||||
Deprecations
|
||||
~~~~~~~~~~~~
|
||||
|
||||
If any publicly facing part of polybar is being deprecated, it should be marked
|
||||
as such in the code, through warnings/errors in the log, and by comments in the
|
||||
wiki. Every deprecated functionality is kept until the next major release and
|
||||
removed there, unless it has not been deprecated in a minor release before.
|
||||
|
|
@ -25,6 +25,12 @@ Welcome to the official polybar documentation.
|
|||
|
||||
dev/packaging
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: Developer Documentation:
|
||||
|
||||
dev/release-workflow
|
||||
|
||||
Getting Help
|
||||
============
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue