Modernize package template

[reece]

Is your feature request related to a problem? Please describe.

The problem is that the biocommons example repo is annoying to apply in practice. Usually I (@reece) apply changes to the example repo and then manually diff (with meld) against biocommons project repos. That makes it hard to keep up-to-date.

Describe the solution you'd like

I'd like the example repo to become a cookiecutter template, based on existing templates that have features that are likely to matter to us. In addition, I'd like to write up the process for maintaining currency of the boilerplate.

New

Update/Fix

• ci github workflow
• cli framework with autocomplete
• code formatting check
• code sec checks
• cookie cutter tool to incorporate template updates
• Ensure that nearly all operations flow through Makefile in order to ensure that local and gh actions invocations are consistent
• ignore ds store
• no double run on push + PR
• packaging and publishing workflow
• py 3.13, depr 3.9
• python 3 (not minor) in Makefile
• pytest w/coverage
• See [PyPI] Trusted Publisher for project biocommons.seqrepo can be made more secure biocommons.seqrepo#180 and /179 for trusted publisher config
• See [PyPI] Trusted Publisher for project biocommons.seqrepo can be made more secure biocommons.seqrepo#180 and /179 for trusted publisher config
• standard docker process, including github multi-platform builds
• standardize pyproject.toml, setup.cfg, setup.py, tox.ini, pytest.ini (others)?
• standardize release devops / config
• add type checking support
• update README pypi links to format like https://pypi.org/project/biocommons.seqrepo/
• workflows centralized in .github repo?
• standardize commit message formats
• update github labeler https://github.com/marketplace/actions/github-labeler
• From hgvs:
  ********************************************************************************
  Please use a simple string containing a SPDX expression for project.license. You can also use project.license-files. (Both options available on setuptools>=77.0.0).
  By 2026-Feb-18, you need to update your project and remove deprecated calls
  or your builds will no longer be supported.
  See https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#license for details.
  ********************************************************************************

Process

• clarify branch & merge strategy
• standardize branch names
• move all release notes to github
• release notes template https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes#configuring-automatically-generated-release-notes

Additional context

For inspiration, see:

• https://github.com/fpgmaas/cookiecutter-uv-example
• https://cookiecutter-uv-hypermodern-python.readthedocs.io/en/latest/
• https://www.astronomer.io/blog/standardizing-astro-projects-with-cookiecutter-and-cruft/
• https://cruft.github.io/cruft/ -- facilitates keeping repos up-to-date with the template
• https://copier.readthedocs.io/en/stable/updating/ (from James)

[jsstevenson]

Noting for myself and maybe others: cruft went through a period of non-maintenance (abandonment?) but as of a few months ago it looks like the original maintainer is back and accepting bug fixes/making new releases again.

We have been running our own cookie cutter template for our labs work but I'd held off on cruft for the above reason -- seems like it's now resolved

[jsstevenson]

Oh, btw, the library copier also can handle some of this. I had bookmarked it to investigate when it seemed like cruft was no longer getting updates https://copier.readthedocs.io/en/stable/updating/

[jsstevenson]

Also see yeoman: https://yeoman.io/learning/

[jsstevenson]

Repos to update

• AnyVar
• HGVS
• bioutils
• seqrepo

Medium priority:

• uta

Lower priority:

• seqrepo-rest
• eutils

[jsstevenson]

Priorities to get done by the hackathon

• devcontainer support for developers (everybody pitching in)
  • would be good
  • already set up for hgvs (is it merged yet?) and vrs-python
• code formatting check (@jsstevenson leading)
  • ruff lint, ruff format
  • refer to https://github.com/GenomicMedLab/software-templates/blob/90b676b7c4aa0f7d1ef304a35e3df50bfa8cbddb/python/%7B%7Bcookiecutter.project_slug%7D%7D/pyproject.toml#L90
  • Kyle objects to EM101, FIX
  • also some helpful precommit https://github.com/GenomicMedLab/software-templates/blob/main/python/%7B%7Bcookiecutter.project_slug%7D%7D/.pre-commit-config.yaml + github action
  • add ruff checks to precommit
  • make sure it's in github actions (python-cqa.yaml)
• Ensure publishing is good to go (@korikuzma leading)
  • Add coolest person as admin to pypi so that we can get new releases out promptly
  • Ensure other publishing configs are in working order
  • Are organization accounts a thing? https://docs.pypi.org/organization-accounts/

Other thoughts/notes

• uv as pip replacement: good for github actions. unsure of whether makefile should force it.
• uv as pyenv declaration: ?
• pytest w/coverage:
  • repos all use pytest
  • coverage/coveralls etc: make sure it's visible, don't hardcode coverage thresholds
• release notes using github releases: yes ✅
  • https://sphinx-github-changelog.readthedocs.io/en/latest/ for sphinx integration
  • brief documentation on protocol for creating releases
• packaging and publishing workflow: based on github tag/release
  • make sure trusted publisher is set up for everything
  • add cool people as pypi admins
  • https://github.com/googleapis/release-please type stuff?
  • explore further?
• type checking support
  • ty
  • pyrefly
  • mypy (more established but slower and less helpful)
  • pyright
  • maybe not ready for prime time (CI/CD) but encourage a specific one for coding/feedback
  • maybe not possible/practical for HGVS
• workflows centralized in .github repo?
  • maybe??
  • yes for issue templates
  • maybe for other things
• code sec checks
• vulture? https://github.com/jendrikseipp/vulture
  • nice to check periodically, but not ideal as ci/cd check
• cli framework with autocomplete
  • James would prefer click
    • Kyle was wrong
  • autocomplete? https://click.palletsprojects.com/en/stable/shell-completion/ ?
• standard docker process, including github multi-platform builds
  • would be good
  • ? https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry
• uv-based builds (https://docs.astral.sh/uv/guides/package/#preparing-your-project-for-packaging)
  • worth exploring
  • current build process seems ok?

[korikuzma]

@jsstevenson Here's the VS Code Dev Container hgvs work: https://github.com/korikuzma/hgvs/tree/dev-containers/.devcontainer