docutils-develop

[Docutils-develop] time to release 0.22.b1 ?

[Guenter M. <mi...@us...>]

Dear Docutils developers,

with a long list a fixes, improvements, and additions since
release 0.21.2 (2024-04-23), how about releasing 0.22?

IMO, we should start with a beta release, to give downstream users an easy
chance to test without breaking installations with `pip` auto-updates.

@Engelbert: would you take care of the release again?

@Adam: I remember you announced interest in collaborating. Is this still
       valid?

Best regards,
Günter

Re: [Docutils-develop] time to release 0.22.b1 ?

[Adam T. <aat...@ou...>]

Dear Günter, all,

>  with a long list a fixes, improvements, and additions since
release 0.21.2 (2024-04-23), how about releasing 0.22?

Sounds good! I want to review the situation around type annotations before releasing, and I might revert some of the changes I have made. There are also a few updates to the packaging metadata we can take the opportunity to make before releasing.

> IMO, we should start with a beta release, to give downstream users an easy
> chance to test without breaking installations with `pip` auto-updates.

Sphinx 8.2. (released last week) is fully compatible with Docutils master (although there are some deprecation warnings). I think we can request that other projects test a release candidate, as with previous releases.

I am happy to help with the release (perhaps publishing a release candidate), I think it might be useful to have more people who can do releases, to share the work and remove pressure on individuals. If this would be helpful, please could I be added to the Docutils PyPI project [1]_? My username on PyPI is ``AA-Turner`` [2]_.

.. [1]: https://pypi.org/project/docutils/
.. [2]: https://pypi.org/user/AA-Turner/

I can probably also co-ordinate with the downstream projects, should this be useful.

Best wishes,
Adam

Re: [Docutils-develop] time to release 0.22.b1 ?

[engelbert g. <eng...@gm...>]

hei

adam should get a invitaionfrom pypi. you are only maintainer ... for now,
i did set felix back to maintainer, as i his off for a long time

maybe we might put out more betas, for users to try before a release, if
they are not developers this might help.

welcome


On Sat, 22 Feb 2025 at 20:01, Adam Turner <aat...@ou...>
wrote:

> Dear Günter, all,
>
> >  with a long list a fixes, improvements, and additions since
> release 0.21.2 (2024-04-23), how about releasing 0.22?
>
> Sounds good! I want to review the situation around type annotations before
> releasing, and I might revert some of the changes I have made. There are
> also a few updates to the packaging metadata we can take the opportunity to
> make before releasing.
>
> > IMO, we should start with a beta release, to give downstream users an
> easy
> > chance to test without breaking installations with `pip` auto-updates.
>
> Sphinx 8.2. (released last week) is fully compatible with Docutils master
> (although there are some deprecation warnings). I think we can request that
> other projects test a release candidate, as with previous releases.
>
> I am happy to help with the release (perhaps publishing a release
> candidate), I think it might be useful to have more people who can do
> releases, to share the work and remove pressure on individuals. If this
> would be helpful, please could I be added to the Docutils PyPI project
> [1]_? My username on PyPI is ``AA-Turner`` [2]_.
>
> .. [1]: https://pypi.org/project/docutils/
> .. [2]: https://pypi.org/user/AA-Turner/
>
> I can probably also co-ordinate with the downstream projects, should this
> be useful.
>
> Best wishes,
> Adam
>
>
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>
> Please use "Reply All" to reply to the list.
>

Re: [Docutils-develop] time to release 0.22.b1 ?

[Guenter M. <mi...@us...>]

Dear Adam, Engelbert, docutils developers,

back from the winter holidays...

On 2025-02-22, Adam Turner wrote:

>> how about releasing 0.22?

> Sounds good! I want to review the situation around type annotations
> before releasing, and I might revert some of the changes I have made.
> There are also a few updates to the packaging metadata we can take the
> opportunity to make before releasing.

Fine. Feel free to commit small, non-controversial changes right away
(bit for bit, so that I can have a look) and discuss the complex and
ambiguous ones either on this list, in private mail or the project tickets.
What would be your proposed timeframe? (I will be offline next week.)

>> IMO, we should start with a beta release, to give downstream users an easy
>> chance to test without breaking installations with `pip` auto-updates.

> Sphinx 8.2. (released last week) is fully compatible with Docutils
> master (although there are some deprecation warnings). 

We should try to solve the deprecation warnings. There should be a
documented way forward, if not, report back and well find a solution 
(as a last restort, we'll turn them into pending deprecation warnings).

Could you also test building a typical Sphinx doctree with the new
"validate__" parser setting set to True?
There may be problems with the custom nodes added by Sphinx.
(The setting was added due to a feature-request by a Sphinx-extension
developer.)

__ https://docutils.sourceforge.io/docs/user/config.html#validate

> I think we can request that other projects test a release candidate, as
> with previous releases.

I have no strong preference whether we call the next release 0.22rc1 or
0.22b1. (It depends on the probability of pending non-trivial changes.)

> I am happy to help with the release (perhaps publishing a release
> candidate), I think it might be useful to have more people who can do
> releases, to share the work and remove pressure on individuals. If this
> would be helpful, please could I be added to the Docutils PyPI project
> [1]_? My username on PyPI is ``AA-Turner`` [2]_.

Could you co-ordinate this with Engelbert, please?

> I can probably also co-ordinate with the downstream projects, should
> this be useful.

Thanks for the offer. For projects where the contact is via github, this
may be helpfull.

sincerely,

Günter

Re: [Docutils-develop] time to release 0.22.b1 ?

[Adam T. <aat...@ou...>]

Dear Günter, Engelbert, all,

[Engelbert]
> adam should get a invitaionfrom pypi.

Thank you! I have accepted the invitation. Please could you also add me to the Docutils project on Test PyPI? [1]

[Engelbert]
> maybe we might put out more betas, for users to try before a release, if they are not developers this might help.

I agree.

[Günter]
> Feel free to commit small, non-controversial changes right away
> (bit for bit, so that I can have a look) and discuss the complex and
> ambiguous ones either on this list, in private mail or the project tickets.

I have made a series of commits starting at [r10019] through to [r10048]. The most notable is [r10043], which removes type annotations for ``docutils.nodes.Node``, as I would like more time to research what the ideal type annotations are, and talk to some static typing experts. Other than that, the commits are mainly small clean-ups, test fixes, etc.

[Günter]
> What would be your proposed timeframe? (I will be offline next week.)

I think we could publish a beta/release candidate at any point, but I have no strong views. I'm also not in any hurry to do so.

[Günter]
> We should try to solve the deprecation warnings. There should be a
> documented way forward, if not, report back and well find a solution
> (as a last restort, we'll turn them into pending deprecation warnings).

You can inspect the deprecation warnings on GitHub [2] (expand the "test with pytest" tab). These are::

    DeprecationWarning: Argument "parser_name" will be removed in Docutils 2.0.
      Specify parser name in the "parser" argument.
      reader: Reader[DocTreeInput] = docutils.readers.doctree.Reader(

    DeprecationWarning: The auxiliary function roles.set_classes() is obsoleted by roles.normalize_options() and will be removed in Docutils 1.0
      set_classes(self.options)

The ``set_classes()`` function is somewhat frequently used [3] and the replacement is very new. Perhaps we should delay the deprecation and use a PendingDeprecationWarning? Likewise with the 'parser_name' argument, support for strings in 'parser' is not yet released, and removal is planned for 2.0, so perhaps we should start with a PendingDeprecationWarning?

[Günter]
> Could you also test building a typical Sphinx doctree with the new
> "validate__" parser setting set to True?
> There may be problems with the custom nodes added by Sphinx.
> (The setting was added due to a feature-request by a Sphinx-extension
> developer.)
>
> __ https://docutils.sourceforge.io/docs/user/config.html#validate

I haven't had time to do so yet, but I will try at some point.

Thanks,
Adam

[1] https://test.pypi.org/project/docutils/
[2] https://github.com/sphinx-doc/sphinx/actions/runs/13728707556/job/38401038459
[3] https://github.com/search?q=%2Fdocutils%5C..*set_classes%2F+language%3APython+NOT+is%3Aarchived++NOT+is%3Afork&type=code

Re: [Docutils-develop] time to release 0.22.b1 ?

[engelbert g. <eng...@gm...>]

any objections for a beta release in the next week or so ?

cheers

On Wed, 19 Feb 2025 at 19:09, Guenter Milde via Docutils-develop <
doc...@li...> wrote:

> Dear Docutils developers,
>
> with a long list a fixes, improvements, and additions since
> release 0.21.2 (2024-04-23), how about releasing 0.22?
>
> IMO, we should start with a beta release, to give downstream users an easy
> chance to test without breaking installations with `pip` auto-updates.
>
> @Engelbert: would you take care of the release again?
>
> @Adam: I remember you announced interest in collaborating. Is this still
>        valid?
>
> Best regards,
> Günter
>
>
>
>
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>
> Please use "Reply All" to reply to the list.
>

Re: [Docutils-develop] time to release 0.22.b1 ?

[Guenter M. <mi...@us...>]

Dear Docutils developers,

On 2025-04-08, engelbert gruber wrote:

> any objections for a beta release in the next week or so ?

I postponed the deprecations/removals that led to DeprecationErrors
downstream as suggested by Adam.

Before releasing, I would like to include 2 patches:

* Set up enhancement proposals in developer documentation.
  https://sourceforge.net/p/docutils/feature-requests/111/
  
  The idea is to expose the proposals to a wider public and catch
  feedback, so that after 0.22 (and possible fixups) we can prepare
  release 1.0 with a complete API definition and backup compatibility
  policy.
  
* Change section handling to not rely on exceptions and reparsing
  https://sourceforge.net/p/docutils/patches/213/

  This patch solves system-message duplicates
  (https://sourceforge.net/p/docutils/bugs/346/), 
  simplifies the rST parser code, and speeds up parsing (a little bit).
  It should be tested for backwards compatibility issues with Sphinx etc.,
  though.


Best regards,
Günter