Re: [Docutils-develop] Adding type hints directly to docutils?

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

On 2024-04-17, Stephen Finucane wrote:
> On Tue, 2024-04-16 at 19:45 +0000, Guenter Milde via Docutils-develop wrote:
>> On 2024-04-15, Stephen Finucane wrote:

Dear Stephen,

>> Contributions are welcome.

> Excellent. I just wanted to make sure it wouldn't be wasted effort.

>> > As a follow-up to the above, are there any significant concerns with
>> > using a tool like 'ruff format' or 'black' to auto-format code before
>> > adding the annotations? It's small thing but it would make the process
>> > of folding in hints somewhat easier if I can rely on tooling to handle
>> > formatting for me.

>> There is support for automatic checks with https://pre-commit.com for
>> Git-based repos [...]
...

> I'm a big fan of pre-commit and use it in many of my projects. However,
> as the project is hosted in SVN I had assumed any git-specific tooling
> would be out the window. More than happy to add this.

It works with `git svn` because the check is at commit stage, not when
commiting with dcommit :)

>> "black" seems too rigid to me (practicability beats purity),
>> especially as we have a large codebase with long legacy and must rely
>> on "git blame" in many cases to find out whether some legacy code may
>> be dropped or has a reason...

> I too have some concerns with the style of black-formatted code - as I
> do with the style of gofmt-formatted Go code - however, it _is_
> robustly maintained, requires little to no configuration on our end,
> and effectively allows formatting to be ignored by developers. It is
> also possible to add a '.git- blame-ignore-revs' file that will allow
> git-blame to ignore certain revisions. This file is also respected by
> some software forges such as GitHub, though I think it's fair to assume
> it is ignored for SVN repos on Sourceforge :)

Would be nice, if it worked for a local git-svn checkout...

> If it's okay with you, I will propose adding hints to a single module
> _with_ black to see how it works. If the output is truly awful, we can
> change tack and try to find a formatter than is slightly closer to what
> we already have but still allows me to avoid fixing formatting in some
> many 100s of files by hand.

I am still sceptical but we may just test.
Is there some tool what only applies auto-formatting to changes?


Mind, that we are on course to the 0.21.2 maintenance release, so no 
changes to the repository master now and only fixes for a week after the
release (until we know if everything went fine).

Thanks Günter