To-do reference for new projects
This doc is linked by Tyrannosaurus after running tyrannosaurus new
.
It may be especially helpful for users new to Python packaging.
See the new project guide
for usage of new
and more detailed information about some of these steps.
To-do list
These are suggested steps for after running tyrannosaurus new --track
.
The --track
option to the new
command tracks usernameororg/project
.
Alternatively, copy the files Tyrannosaurus generated into your repo,
or use --track
and just modify the git remote afterward.
Tip
Check git config user.name
, git config user.name
, and your
GPG keys: git config --global user.signingkey
Getting your first commit on GitHub
Create a repo: Create an non-initialized repository under
userororgname/projectname
. (Don’t add a readme, etc.) Install Probot Settings: in your repo.
Delete unwanted files: Delete
.github/labels.json
,.github/workflows/labels.yml
,.travis.yml
, and.azure-pipelines.yml
, assuming you’re not using them. You might also not wantcodemeta.json
,CITATION.cff
,environment.yml
, orVagrantfile
.Modify
pyproject.toml
andREADME.md
.Add an entry to
CHANGELOG.md
and rungit commit -m "feat: initial code"
(probably twice).
Tip
If a linter such as black fails on commit, just run git commit again to accept the linted version.
Tip
Always run tyrannosaurus sync
or poetry lock
after modifying dependencies.
Tip
A Commitizen pre-commit hook checks commit
messages. To enable it, you need to
run pre-commit install --hook-type commit-msg
.If it’s too restrictive,
modify [tool.commitizen]
in pyproject.toml or remove the pre-commit-config entry.
Configuring external integrations
External services require additional steps. These are making accounts, installing GitHub apps, adding webhooks, and adding GitHub secrets. See the report config guide for discussion.
PyPi: On PyPi, create a new project and get a repo-specific token. In your GitHub secrets page (under Settings), add
PYPI_TOKEN
.Docker Hub: Tell DockerHub to track your repo with source
/v[0-9]+.*/
and tag{sourceref}
. On your GitHub repo ⮞ Settings ⮞ Webhooks ⮞ your docker hook ⮞ Edit, checkReleases
.
Readthedocs: Set up readthedocs to track your repo.
Code quality / coverage (1): Set up Code Climate, Scrutinizer, and either CodeCov or Coveralls.
Code quality / coverage (2): Add
CODECOV_TOKEN
to your GitHub secrets, if you’re using CodeCovSlack notifications: For important success/failure notifications, add
SLACK_WEBHOOK
as a GitHub secret and setuse_slack=true
in.github/action-options.json
.
Tip
If you choose not to install Probot Settings, check out the suggested branch protection rules in .github/settings.yml
.
Also confirm that Dependabot alerts and security updates are enabled under Security & analysis.
Currently, Dependabot updates are only available on a GitHub organization.
Your first GitHub release
Follow these steps to publish to GitHub releases, the GitHub Container Registry, Docker Hub, and PyPi.
If you’re using the default Azure-pipelines file, you’ll also publish to Azure’s container registry.
If you want to publish to Conda-Forge, follow
the anaconda recipe-generation steps
after the package is on PyPi to get an initial recipe (meta.yaml
) file.
Your project’s CONTRIBUTING.md
will list the steps to make subsequent releases.
(See Tyrannosaurus’s own contributing guide.)
Final thoughts
Note the normal way to update the main branch: 1. Push to a remote branch or fork and make a pull request against main branch. 2. When the pull request tests pass, submit a review on the pull request, and rebase it into main.
Review Semantic Versioning,
Keep a Changelog, and
Conventional Commits.
Consider getting a DOI for scientific software.
If you’re using Jupyter, consider adding [nbstripout](https://github.com/kynan/nbstripout) to your
pre-commit-config.yaml
to avoid ending up with a massive git history.
If you want to create a package on Conda-Forge, see the
anaconda integration guide.
You may want to add new code quality integrations, like codacy. Consider adding shields for those. Other good tools to consider include github-labeler and Towncrier.
Commitizen can be used to generate a changelog. In my experience, those changelogs are not great because
(1) commit messages are too messy, (2) the feat:
, fix:
, etc. commit types don’t match up with
those in keep-a-changelog, (3) it fails completely if one commit message is off, (4) it’s hard to modify the style
at a later date without completely rewriting the git history or adding a plugin for Commitizen, and (5)
Commitizen destroys any extra text you add to your Changelog, such as a ”Conventions” section.
Instead, I just add to the changelog manually.
Warning
Probot Settings has a privilege escalation issue.
Either accept that as a caveat, list .github/settings.yml
in .github/CODEOWNERS
, or disable it after your initial push.
Caution
Both tyrannosaurus sync
and Commitizen’s bump
copy version numbers. They won’t always play well together.
I recommend not using it. In the future, you may be able to point tool.tyrannosaurus.sources.version
to tool.commitizen.version
(leaving tool.commitizen.version_files
empty).
Reference of commands
These commands might be useful:
tyrannosaurus sync
to sync metadata and nothing elsetyrannosaurus clean --aggressive
to remove lots of temp filestox
to build, test, build docs, and run some static analysespoetry update
to find updated dependency versions (major or minor)tyrannosaurus recipe
to generate a Conda recipe
These commands are run automatically via either Tox or a GitHub action, but you can run them locally too:
poetry install
to install and nothing morepoetry build
to build wheels and sdistspoetry publish
to upload to PyPidocker build .
to build a docker image