Maintainer Guide framework #7
Conversation
|
That is great. The more eyes, the better. All QC-Devs are welcome to "star" and "watch" this repository, so you get updates on future pull requests. This repo should ultimately represent our common wisdom on how to best manage Git repos, which can be difficult to follow by just a single person because the landscape evolves so quickly. |
| [RSI]: https://en.wikipedia.org/wiki/Repetitive_strain_injury | ||
|
|
||
|
|
||
| ## Add a Few Essential Files |
There was a problem hiding this comment.
Do we need a requirements.txt in order for people to build up a reproducible virtual environment?
There was a problem hiding this comment.
This would be useful for repositories that are not Python packages, but that use a Python environment. When developing a Python package, the current practice is to specify dependencies in pyproject.toml. (See https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#dependencies-and-requirements) I'd like to cover this in the to-be-written tutorial on setting up a Python package.
We can also add an alternative mini-tutorial for non-python-package repositories. In that case, I'd recommend working with pip-tools because it is created to improve the reproducibility of Python environments beyond what can be done with ordinary pip. (We use this for publication Git repositories.)
In this minimal.md, I'd like to include only those files that need to be present in all scenarios.
There was a problem hiding this comment.
I've clarified the scope in MAINTAINING.md to clarify the purpose of minimal.md, and I've added stub to write something for repositories that may benefit from pip-tools
|
|
||
| Note that some of the tools listed in `.pre-commit-config.yaml` | ||
| rely on additional configuration settings, | ||
| most notably in `pyproject.toml`, which we'll cover later. |
There was a problem hiding this comment.
Shall we also add .bumpversion.cfg which is closely related to pyproject.toml as it's a nice tool for version management? Then we can use GitHub actions to automatically update the minor version with a squash merge and release via PyPI. Major releases can be managed with our choice.
There was a problem hiding this comment.
I'm not very familiar with this. How does the bumpversion package compare to setuptools_scm. Both seem to have similar goals?
I've been using setuptools_scm for version management of IOData, which works quite well. It supports several conventions for interpreting git tags as version numbers, and integrates well with GitHub actions for creating releases on PyPI. It is also well maintained because it is integrated with setuptools.
I'd like to cover this in a later mini-tutorial on setting up a Python package, which is beyond the scope of this minimal setup. We can pick up this thread in a later PR?
There was a problem hiding this comment.
Also for this, I've tried to clarify the scope of minimal.md.
|
Feel free to suggest changes with the suggestion tool, see point 8 in https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request#starting-a-review |
This is a first step towards addressing #5. All comments welcome. For some of the items that are still TODO, I believe we can refer to external tutorials, maybe with some minor additions.
I will open another PR on the IOData repo to better fit the minimal setup tutorial.