docs: module inclusion policy #119
Conversation
| ``examplemodule.*`` is in the standard library by definition so long | ||
| as ``exmaplemodule`` is in the standard library. | ||
|
|
||
| * Platform-specific modules are **best-effort**: ``stdlib-list`` is currently collected |
There was a problem hiding this comment.
NB: This rule reflects our current practice, but maybe we should change that. In particular, it probably wouldn't be too hard to collect modules on Windows and macOS as well in our current listgen workflow.
There was a problem hiding this comment.
I agree this is inline with current practice.
If we can expand platform support with automation, then we should add it.
Maybe this is more like Tier 1 is Linux, Tier 2 is Win/Mac?
Sets the stage for what this library finds most important.
There was a problem hiding this comment.
I think it would be a big mistake to not include windows and mac as tier 1 platforms, more developers are probably on those platforms than on linux (SO dev survey ). It's also easy to run github pipeline jobs on those platforms...
There was a problem hiding this comment.
@thebjorn the tiers here are intended to be descriptive, not prescriptive -- IMO Windows and macOS should indeed be Tier 1, but currently aren't. So the policy as-merged here should probably document them as Tier 2 until someone puts the work into making the listgen workflow work across those as well 🙂
There was a problem hiding this comment.
I haven't looked at the workflow in any real depth, but would it just boil down to explicitly setting shell: bash and either using an OS matrix or a specific set of includes to get win/mac on-board? (like line 61-73 here: https://github.com/thebjorn/pydeps/blob/master/.github/workflows/ci-cd.yml#L61).
There was a problem hiding this comment.
I'd envision changing https://github.com/pypi/stdlib-list/blob/c3a45e824174fb298bba17cb3afb04c0ba9953a3/.github/workflows/listgen.yml to have a more fan-out kind of step, where after a pre-list is done, fan out to each platform, generate on that platform, upload the artifact, and then a final step to download all of the generated files for that version, and combine them all to the final versioned list.
There was a problem hiding this comment.
Hmm... looks like there is a makefile (why?), creation of a virtualenv (why do this in a pipeline that is isolated to a specific python version?), and hard coding of the .env/bin/python path to work in the created virtualenv. Aside from that there should only be changes corresponding to what I've done here: main...thebjorn:stdlib-list:main
There was a problem hiding this comment.
creation of a virtualenv (why do this in a pipeline that is isolated to a specific python version?),
I did this for two reasons:
- A venv here ensures that we don't load in the system site packages by default. This is intended as a defensive maneuver: nothing stops the OS Python distribution from modifying the stdlib directly, but we can at least perform a small amount of site isolation from anything in the system site packages.
- I think environment isolation is a good general practice, especially following PEP 668. GitHub runners are arguably their own ephemeral environment anyways, but creating a venv is cheap and reduces the amount of global state to think about.
(I have no good argument for the Makefile. It's just what I'm used to.)
|
Merging as is, for future iteration. Thanks @miketheman and @thebjorn! |
Very WIP, feedback greatly desired. CC @miketheman 🙂
Closes #80.