Quickstart Guide

Requirements

Install Cookiecutter:

$ pipx install cookiecutter

Install Poetry by downloading and running get-poetry.py:

$ python get-poetry.py

Install Nox:

$ pipx install nox

pipx is preferred, but you can also install with pip install --user.

It is recommended to set up Python 3.6, 3.7, and 3.8 using pyenv.

Creating a project

Generate a Python project:

$ cookiecutter gh:cjolowicz/cookiecutter-hypermodern-python \
  --checkout="2020.4.15"

Change to the root directory of your new project, and create a Git repository:

$ git init
$ git add .
$ git commit

Local testing

Run the full test suite:

$ nox

List the available Nox sessions:

$ nox --list-sessions

Continuous Integration

GitHub

1. Sign up at GitHub.

2. Create an empty repository for your project.

3. Follow the instructions to push an existing repository from the command line.

PyPI

1. Sign up at PyPI.

2. Go to the Account Settings on PyPI, generate an API token, and copy it.

3. Go to the repository settings on GitHub, and add a secret named PYPI_TOKEN with the token you just copied.

TestPyPI

1. Sign up at TestPyPI.

2. Go to the Account Settings on TestPyPI, generate an API token, and copy it.

3. Go to the repository settings on GitHub, and add a secret named TEST_PYPI_TOKEN with the token you just copied.

Codecov

1. Sign up at Codecov, and install their GitHub app.

2. Add your repository to Codecov.

Read the Docs

1. Sign up at Read the Docs.

2. Import your GitHub repository, using the button Import a Project.

Releasing

1. Bump the version using poetry version. Push to GitHub.

2. Publish a GitHub Release.

3. GitHub Action triggers the PyPI upload.

Release notes are pre-filled with titles and authors of merged pull requests.

Use labels to group the pull requests into sections:

Label	Section
breaking	💥 Breaking Changes
enhancement	🚀 Features
removal	🔥 Removals and Deprecations
bug	🐞 Fixes
performance	🐎 Performance
testing	🚨 Testing
ci	👷 Continuous Integration
documentation	📚 Documentation
refactoring	🔨 Refactoring
style	💄 Style
build	📦 Build System and Dependencies

GitHub creates the bug, enhancement, and documentation labels for you. Create the remaining labels on the Issues tab of your GitHub repository.

Caveats

When upgrading Sphinx or its extensions using Poetry, also update the requirements located in docs/requirements.txt for Read the Docs.