Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update versioning docs to be explicit about our versioning workflow #1373

Merged
merged 1 commit into from
Nov 4, 2022
Merged

Update versioning docs to be explicit about our versioning workflow #1373

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
33 changes: 31 additions & 2 deletions docs/contributing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -200,6 +200,33 @@ put up for review.

.. _Transifex: https://www.transifex.com/readthedocs/sphinx-rtd-theme

Versioning
==========

..
TODO make these instructions organization wide. We've talked about
standardizing packaging version and tooling here (bumpver instead of
bump2version).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if I would make this organization-wide. It can vary for every project. Release processes also lean towards automation, although I'm not a big fan.

For this project, we could work more with dynamic generation of artifacts for each release.

A versioning guide should contain more details on the semantics of the versions. For instance, can a patch release contain translations? What can be changed in a minor release? How do we handle deprecation? Etc.


In between releases, the package version specified will always be a alpha
release, matching ``1.1.1alpha1``.

As pull requests are merged and the release impact changes, this version will
incremented ahead of release. For example, if we merge a new feature pull
request, we'd run ``bump2version minor`` to increment ``1.1.1alpha1`` to
``1.2.0alpha1``.

To put out a release for testing, we will upload a release candidate. We would
run ``bump2version release`` to increment ``1.2.0alpha1`` to ``1.2.0rc1``.

After a testing period, the release candidate can become a full release. We
would run ``bump2version release`` again to increment ``1.2.0rc1`` to ``1.2.0``.

After the release process below, we increment the version again, so that the
development version -- the version found in the repository -- is always greater
than the most recent release. We follow up with another pull request by running
``bump2version patch``, which increments ``1.2.0`` to ``1.2.1alpha1``.

Releasing the theme
===================

Expand All @@ -222,7 +249,9 @@ To release a new version of the theme, core team will take the following steps:
version. But take care that it isn't also bumping versions of dependencies
in ways that are risky to the release. *If* ``package-lock.json`` changes, you
need to commit it to git and tag it together with your release.
#. Commit these changes.
#. Commit these changes to a pull request.
#. Merge the pull request after review.
#. Check out ``master`` branch locally for tagging
#. Tag the release in git: ``git tag $NEW_VERSION``.
#. Push the tag to GitHub: ``git push --tags origin``.
#. Upload the package to PyPI:
Expand All @@ -235,7 +264,7 @@ To release a new version of the theme, core team will take the following steps:

#. Finally, open a new pull request updating the development release version to
the next patch by running ``bump2version patch``. Open a pull request with
this change.
this change. See `Versioning`_ above for more details.

.. _PEP440: https://www.python.org/dev/peps/pep-0440/
.. _semantic versioning: http://semver.org/