personal repo bootstrap
BSD-3-CLAUSE License
This is my personal python repository bootstrap.
Feel free to use it as a launching point for your next project!
https://github.com/tlambert03/pyrepo-cookiecutter/tree/simple
For simplified/minimal starter package see the simple branch
|
---|
I recommend using cruft
instead of
cookiecutter (this will let you update it easily later)
pip install cruft
cruft create https://github.com/tlambert03/pyrepo-cookiecutter
or you can use cookiecutter as usual:
pip install cookiecutter
cookiecutter https://github.com/tlambert03/pyrepo-cookiecutter
git init
and install pre-commit
After creating the repo, you'll want to initialize a git repo.
This is important: you won't be able to
run pip install -e .
without runninggit init
cd <your-package-name>
git init
git add .
git commit -m 'build: Initial Commit'
Optionally, install pre-commit:
pip install pre-commit
pre-commit autoupdate
pre-commit install
git add .
git commit -m 'chore: update pre-commit'
To run tests locally, you'll need to install the package in editable mode.
I like to first create a new environment dedicated to my package:
mamba create -n <your-package-name> python
mamba activate <your-package-name>
Then install the package in editable mode:
pip install -e .[test]
if you run into problems here, make sure that you ran git init above!
Finally, run the tests:
pytest
If you have the GitHub CLI installed, and would like to create a GitHub repository for your new package:
gh repo create --source=. --public --remote=origin --push
alternatively, you can follow github's guide for adding a local repository to github
pre-commit run -a
python -m build
, not python setup.py
!pyproject.toml
pyproject.toml
, withsrc
layout (How come?)TWINE_API_KEY
env var on github). See Deploying to PyPI below.--pre
to installflake8
, autoflake
, isort
, pyupgrade
,strict
mode)check-manifest
test to checkWhen I'm ready to deploy a version, I tag the commit with a version number and
push it to github. This will trigger a github action that will build and deploy
to PyPI. (see the "deploy" step in workflows/ci.yml
). The version number is determined by the git tag using
hatch-vcs... which wraps
setuptools-scm
To auto-deploy to PyPI, you'll need to set a TWINE_API_KEY
environment
variable in your github repo settings. You can get this key from your pypi
account. Then add it to your github
repository settings as a secret named TWINE_API_KEY
. (see github
docs)
(the name TWINE_API_KEY
is specified in workflows/ci.yml
)
git tag -a v0.1.0 -m v0.1.0
git push --follow-tags
# or, specify a remote:
# git push upstream --follow-tags
if you're curious, see also some thoughts on semantic releases below
Conventional Commits is a specification for adding human and machine readable meaning to commit messages. Using it faithfully will allow you to automate a lot of things (changelogs, versioning, ...) at release time. To use it here:
Use the conventional-pre-commit
step in pre-commit. It will force you to use
conventional commits locally.
[VS Code]: Add the Conventional Commits extension, making it easier to create conventional commits.
This still doesn't protect GitHub PR commits, so add the Semantic PRs GitHub App to check that PR titles follow the Convention Commits Spec (and require squash commits)
Protect the main
branch:
main
Semantic PRs
check to pass for mergingsemantic-release
to push to that branch.Future: use frappucino or
griffe to detect breaking API
changes & add a GitHub action to enforce a !
in the title or BREAKING CHANGE
footer.
I'm still not sure how I feel about SemVer. Seems better than nothing, but also totally broken. I highly recommend these articles for insight:
One of the biggest problems with SemVer is humans implementing it (see
ZeroVer 😂). One approach is to use fully-automated version
& release management to take the human out of it.
semantic-release is
popular in the javascript world, and a
python-semantic-release
variant exists. If you want to try it, this repo configures that in
pyproject.toml
:
python-semantic-release
on GitHubci.yml
)cruft
)This template may change over time, bringing in new improvements, fixes, and
updates. To update an existing project that was created from this template
using cruft, run cruft update
in the root of the project. See cruft
docs for details.