Create a contribution and developer guide for backports maintained by jaraco

[jaraco]

In #123028 (comment)_, we identified a need to document better the methodology used by jaraco to maintain the backports of importlib.resources, importlib.metadata, and zipfile.Path, and maybe also other backports such as backports.tarfile, configparser, and singledispatch.

Also, let's make sure that the importlib.resources docs reference importlib_resources.

[jaraco]

I created this documentation. My thinking is we should link that documentation from the source code for the relevant projects, so it'll appear in both CPython and the source project.

I was thinking there would be a separate document for "Contributing," but when I started drafting it, I couldn't think of a lot more to add than to refer to the development methodology. In general, I'd like users to feel free to file issues naturally, and contributors to be aware of the methodology (which they would likely be if they got to the source).

@encukou Would you take a look and let me know what you think? Does this document largely (fully) clarify the situation?

[encukou]

Thanks! A lot of this is not obvious from reading the code.

I guess the main thing for “Contributing” would be how to run the tests and lints.
I look for that kind of info for unfamiliar projects in CI settings, which aren't very readable to the uninitiated.

Here, it seems the correct way is to install tox, and run that. Is it enough?
What should one do if a linter or format checker find issues? (Or are they fixed automatically -- then it'd be polite to warn users that running tests will change their files?)
The tools used are kind of hidden so it'd be good to at least link to their documentation.

[jaraco]

It's subtle, but the "skeleton" badge does link to the guidance around those concerns. It doesn't specifically mention that the linter/formatter checks are non-invasive; I've added that in jaraco/skeleton@87ff557.

I've been reluctant to add more detail about the common concerns, as that adds more boilerplate (and potential for merge conflicts and maintenance toil) to every project. I do think it might make sense to add another URL to the metadata to point to this guidance. It might also make sense to re-frame the guidance as first about contributing and secondarily about maintaining. Maybe even the badge should be renamed to "contributing" instead of "skeleton". I'll raise that issue in jaraco/skeleton#100.

[encukou]

Yes, the link to the document itself is well hidden, as are the contributor instructions inside (“Running Tests” under “Features”, right?). Reframing it for contributors would help, if you don't want to split it.

[jaraco]

Yes, that's right. The document was originally written as an overview of the packaging strategy and has evolved to have some contributor guidance. The two should be separated and clearly marked as they address largely different audiences.

[jaraco]

I've added references to the documentation in the three primary projects (upstream). Those changes will trickle into CPython in due course. I'll use jaraco/skeleton#100 to track ongoing improvements to the visibility of a contributor guide.

[encukou]

Thank you!
When they get to CPython, could you put them in comments rather than docstrings? They aren't really relevant for users, e.g. in help().

[jaraco]

When they get to CPython, could you put them in comments rather than docstrings? They aren't really relevant for users, e.g. in help().

I'd like to avoid having the codebases diverge (and then maintain that divergence). I can convert them to docstrings, but that should happen in the backports and then will apply when synced with CPython. Not sure when I'll get to it, but I'm acknowledging the request and will work on it when time permits.