It also uses pre-commit to lint the code you’re going to commit.
Setting up a Development Environment#
Clone the project and change into its directory:
$ git clone firstname.lastname@example.org:sscherfke/typed-settings.git $ cd typed-settings
Create a virtual environment in your preferred ways:
$ hatch shell
This not only creates and activates an environment but also installs/updates all development dependencies and pre-commit.
$ mkvirtualenv typed-settings
$ virtualenv .env $ source .env/bin/activate
$ python -m venv .env $ source .env/bin/activate
If you did not use Hatch, install all development requirements and Typed Settings itself in development mode:
(typed-settings)$ pip install -e .[dev] # Not needed with hatch (typed-settings)$ pre-commit install --install-hooks
(typed-settings)$ flake8 PATH... (typed-settings)$ mypy PATH... (typed-settings)$ # or (typed-settings)$ hatch run lint
(typed-settings)$ black PATH... (typed-settings)$ isort PATH... (typed-settings)$ # or (typed-settings)$ hatch run fix [PATH...]
Pre-commit also runs all linters and formatters with all changed files every time you want to commit something.
You run the tests with pytest.
It is configured to also run doctests in
docs/ and to test the examples in that directory,
so do not only run it on
(typed-settings)$ pytest (typed-settings)$ # or (typed-settings)$ hatch run test
Hatch provides a shortcut for quickly running the tests and measure the coverage:
(typed-settings)$ hatch run cov
You will not get to 100% with this though, since some compatibilty code will not be executed.
You can also use nox to run tests for all supported Python versions at the same time. This should get you to 100% coverage.
nox to build a package, test it, and lint it:
Sphinx is used to build the documentation. The documentation is formatted using reStructuredText (maybe we’ll switch to Markdown with the MyST parser at some time). There’s a makefile that you can invoke to build the documentation:
(typed-settings)$ make -C docs html (typed-settings)$ # or (typed-settings)$ hatch run docs (typed-settings)$ (typed-settings)$ make -C docs clean html # Clean rebuild (typed-settings)$ # or (typed-settings)$ hatch run clean-docs (typed-settings)$ (typed-settings)$ open docs/_build/html/index.html # Use "xdg-open" on Linux
When you commit something, take your time to write a precise, meaningful commit message. In short:
Use the imperative: Fix issue with XY.
If your change is non-trivial, describe why your change was needed and how it works. Separate this from the title with an empty line.
Add references to issues, e.g. See: #123 or Fixes: #123.
When any of the linters run by Pre-commit finds an issue or if a formatter changes a file, the commit is aborted. In that case, you need to review the changes, add the files and try again:
(typed-settings)$ git status (typed-settings)$ git diff (typed-settings)$ git add src/typed_settings/...
Releasing New Versions#
Releases are created and uploaded by the CI/CD pipeline. The release steps are only executed in tag pipelines.
To prepare a release:
CHANGELOG.rst. Use an emoji for each line. The changelog contains a legend at the bottom where you can look-up the proper emoji.
Update the version in
Commit using the message
Bump version from a.b.c to x.y.z.
Create an annotated tag:
git tag -am 'Release x.y.z' x.y.z.
git push --atomic origin main x.y.z.
The CI/CD pipeline automatically creates a release on the testing PyPI. Check if everything is okay.
Manually trigger the final release step.