René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Tooling is somewhat poorly discoverable","articleBody":"The [Running Tests](https://github.com/gitpython-developers/GitPython?tab=readme-ov-file#running-tests) section of the readme includes some information about tools, such as linters, to use with the project, how to run them, and where their configuration files are. However, this has not been updated in a while, and:\r\n\r\n- CI is the primary way tools are run for this project, but the CI workflows are not mentioned.\r\n- `pre-commit` is used for several checks, but its own configuration file is not mentioned.\r\n- Information on preconditions for running tests in forks is outdated: CI runs on all branches, so the fork need not have a `main` branch. (In practice, forks will, but the key is that people do not need to develop their features on their fork's default branch.)\r\n\r\nThe bigger issue, though, is how recent changes from pull requests I have opened have made the situation worse:\r\n\r\n- `tox` is not mentioned in the readme.\r\n- `tox.ini` defines an `html` environment to test building documentation, but does not list it in `env_list`, so it is hard to notice it exists. The reason it is not listed is that it should not be run by default, because it writes (and overwrites) files in the actual `doc/build` directory. If `doc/Makefile` is made to support custom build directories, then that `tox` environment can be made to write documentation into its temporary directory, and it can be listed (and otherwise treated) like the other `tox` environments.\r\n- `tox.ini` specifies Python 3.9 for everything that doesn't need to run on multiple versions of Python, for compatibility with Cygwin, and it allows missing interpreters to be skipped without error, also for compatibility with Cygwin. But users may well not have Python 3.9, in which case these just don't run, *and may not be noticed*. `tox.ini` should not multiply those environments for multiple Python versions, but it should list backup versions (every other supported version, in some reasonable order) as well, for those environments to use.\r\n- Users can run `black .`, but `black` is not being run on CI, nor via `pre-commit`, which makes it easy to forget to run it or, if one is less familiar with the project's tooling, to be unaware that it is even available.\r\n- Every time I have made a change to a shell script in this project, I have run [`shellcheck`](https://www.shellcheck.net/). But as far as I know, I have not even mentioned this tool anywhere, only [alluded to its use](https://github.com/gitpython-developers/GitPython/pull/1661#issuecomment-1719392766). This is not quite an issue of the *tool*'s discoverability: most people who contribute to this project probably won't edit a shell script, but when someone does, it would be useful for `shellcheck` to run on CI and (when in use) via `pre-commit` to make possible problems with the changes discoverable.\r\n\r\nIn addition, it is arguably a discoverability issue that `flake8` is not listed as a development dependency (which is not necessary for running it via `pre-commit`, which takes care of installing it in a virtual environment it manages). However, I am still reluctant to add it and its plugins as development dependencies, because I think much older versions with possibly different behavior would be gotten on Python 3.7, and because I still intend to replace it with `ruff`.\r\n\r\nThrough my work on these issues so far, I have come to think all this could be fixed together and in the same PR that would also fix #1690 and #1691. However, in case the scope turns out to be too large, I'm making this issue so the matter is not forgotten about. Having this also has the benefit that there is less to document in a PR that covers it along with other things.","author":{"url":"https://github.com/EliahKagan","@type":"Person","name":"EliahKagan"},"datePublished":"2023-10-04T02:06:21.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/1692/GitPython/issues/1692"}