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.

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

Add changelog entry for docutils 0.18 support #1389

Merged
merged 2 commits into from
Dec 15, 2022
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
Add changelog entry for docutils 0.18 support
benjaoming committed Dec 15, 2022

Verified

This commit was signed with the committer’s verified signature. The key has expired.
commit 91770b4b77b2673c52965d3de4642f32819ef6eb
15 changes: 15 additions & 0 deletions docs/changelog.rst
Original file line number Diff line number Diff line change
@@ -9,6 +9,21 @@ Development version (|development_version|)

.. |development_version| replace:: 1.1.2alpha1

Dependency Changes
------------------

* docutils 0.18 is supported. (#1381)

Note for users of Sphinx<3
--------------------------

If you have pinned your documentation project to use versions of
``sphinx<1.8.6`` or ``Sphinx>=2.0,<2.4.5``, you need to either
add ``docutils<0.18`` to your requirements since newer versions of docutils are incompatible with these older Sphinx versions
**or**
update to a later release of Sphinx that has docutils correctly pinned.
Read more in `this comment <https://github.com/readthedocs/sphinx_rtd_theme/pull/1304#issuecomment-1266924478>`.
Copy link
Collaborator

Choose a reason for hiding this comment

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

For the future, basically no one looks at the changelog, so I don't like to spend much time here. But, at this point we should always guide users toward upgrading. There is a lot of Technically Correctness in the suggestion here that I think we can just skip entirely, and make our guidance "just upgrade Sphinx".

Suggested change
If you have pinned your documentation project to use versions of
``sphinx<1.8.6`` or ``Sphinx>=2.0,<2.4.5``, you need to either
add ``docutils<0.18`` to your requirements since newer versions of docutils are incompatible with these older Sphinx versions
**or**
update to a later release of Sphinx that has docutils correctly pinned.
Read more in `this comment <https://github.com/readthedocs/sphinx_rtd_theme/pull/1304#issuecomment-1266924478>`.
If you cannot use a more recent Sphinx release,
you should at least ensure you are using the most recent release for your major version.
Currently, these are Sphinx `1.8.6` and `2.4.5`.
Older releases may install unsupported versions of several dependencies, including Jinja2 and docutils.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

basically no one looks at the changelog

The ones that do have a good reason :)

Copy link
Collaborator

Choose a reason for hiding this comment

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

Aye, and for anything major we should put this information somewhere more accessible, but agreed that for cases like this it's nice to have some artifact.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

It's a good "read more" reference for blog posts and toots 👍


.. _release-1.1.1:

1.1.1