Document default repository and continuous integration setup

[tovrstra]

As mentioned in #2, a practical setup guide would bring consistency and helps transferring knowledge on all technicalities of setting up a repo.

The following issue has most of the ingredients, but needs to be transformed into a readable form with more detail: theochem/iodata#313

TODO:

• Create initial framework for such documentation. See Maintainer Guide framework #7
• Recommended branch protection rules
• Setuptools
• Recommended Packages to facilitate development
• Non-python-package repository with venv and pip-tools
• Pre-commit. See Maintainer Guide framework #7
• Unit testing
• Code coverage
• Documentation build and deployment
• Deployment on PyPI
• Deepsource analysis
• Sourcery AI pull request review
• Code factors analysis
• Changelogs
• Sphinx docs
• Jupyter Book

[PaulWAyers]

Should we add a template repository? That, plus a setup guide, could be a good way to handle the issue IMHO.

[tovrstra]

There are advantages and disadvantages to using a template repo. I'm currently inclined not to do it, which may seem surprising. I'll try to explain. Templates seem quite nice but are actually tricky, I think.

The main advantage is that you can quickly set up a new repo with all the bells and whistles. The cookiecutter or GitHub template repositories can make this setup very smooth. (I have some experience with the cookiecutter.)

The main challenge is keeping the template repository up to date and working, which may outweigh the benefit of setting up a new repo quickly. For example, the official cookiecutter-pypackage template is outdated: it uses Travis for CI, no GitHub actions, and no pre-commit. This template has 122 contributors, so I'd expect it to be cutting-edge. Some of this may be a matter of taste, but also the number of open issues and pull requests seems to indicate that maintaining a template repo is not easy.

I think the reason is that CI is needed to keep the template itself in good shape, and there are no established tools for doing CI for a template. (There is a workflow with GitHub Actions for testing the cookiecutter-pypackage template itself, but it seems incomplete and it fails.) I believe the template authors put a lot of effort into this, but it's just not easy to get right.

So I'm not inclined to go down the template rabbit hole, but we should have a practical solution for getting started with a new repo and also updating an existing one (which templates cannot do). Documentation (including pointers to good external documentation) and one or a few working examples seem more feasible. A good and real-life example is easier to maintain than a template. Building a good CI infrastructure for a new repo is also a gradual process. As you add more and more CI components, you have to learn how to use them effectively. My current impression is that this learning aspect is more important than having the files in place.

Anyway, this is just my current perspective. The situation can always change.

[PaulWAyers]

Thanks for the detailed description. I agree, there are some trade-offs. Since right now I think creating a template repo. is a low priority anyway, I think we can say "for now, no" and revisit later.

[tovrstra]

I agree. We can take a gradual approach and still decide to create a template later. Documentation is needed in either case, so starting with documentation seems like a safe move.

[FanwangM]

When a first-time contributor makes contributions to a repo, some may start working on the main branch of the forked repo, which can mess up the git history. We should try to prevent a pull request from being merged from the main branch of the forked repo. It would be beneficial if more instructions should be given in https://github.com/theochem/.github/blob/main/contributing/development_setup.md.

If you think this is needed, I can try to cook up something. @PaulWAyers @tovrstra

[tovrstra]

@FanwangM Thank you for that suggestion. It would be good to briefly mention this in development_setup.md as a heads-up for step 2 in the instructions in contributing/workflow.md. In that step 2, we can add a few bullets with reasons for using a new branch instead of making pull requests from the forked main. The problems I've seen with it are:

• The main branch of the fork becomes incompatible with the main branch of the original repo. Fixin this requires a force-push to the forked repo. (A force-push is not elegant and should be avoided in a default workflow.)
• Maintainers of the original repo cannot push additional commits to the PR, despite having this feature swithced on in the pull request. See for example: New version overlap.py to fix_factorial2 #309 with unittest named test_factorial2 iodata#316 (comment)