Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document default repository and continuous integration setup #5

Open
16 tasks
tovrstra opened this issue Jun 15, 2024 · 6 comments
Open
16 tasks

Document default repository and continuous integration setup #5

tovrstra opened this issue Jun 15, 2024 · 6 comments

Comments

@tovrstra
Copy link
Member

tovrstra commented Jun 15, 2024

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
Copy link
Member

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

@tovrstra
Copy link
Member Author

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
Copy link
Member

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
Copy link
Member Author

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
Copy link

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
Copy link
Member Author

@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:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants