Update CONTRIBUTING.md from template-python repo

.github/CONTRIBUTING.md

@@ -2,116 +2,73 @@
 
 ## Table of Contents <!-- omit in toc -->
 
-- [Git](#git)
-- [GitHub](#github)
+- [Summary](#summary)
   - [Contributors](#contributors)
   - [Maintainers](#maintainers)
+- [Git](#git)
 - [Python](#python)
+  - [Python code style](#python-code-style)
   - [Poetry](#poetry)
-  - [Code style](#code-style)
 - [Docker](#docker)
 
-## Git
-
-- _[Why use Git?](https://www.git-scm.com/about)_ Git enables creation of multiple versions of a code repository called branches, with the ability to track and undo changes in detail.
-- Install Git by [downloading](https://www.git-scm.com/downloads) from the website, or with a package manager like [Homebrew](https://brew.sh/).
-- [Configure Git to connect to GitHub with SSH](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/connecting-to-github-with-ssh)
-- [Fork](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/fork-a-repo) this repo
-- Create a [branch](https://www.git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) in your fork.
-- Commit your changes with a [properly-formatted Git commit message](https://chris.beams.io/posts/git-commit/).
-- Create a [pull request (PR)](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/about-pull-requests) to incorporate your changes into the upstream project you forked.
-
-## GitHub
-
-Here are some suggested GitHub practices:
+## Summary
 
 ### Contributors
 
+**PRs welcome!**
+
+- **Consider starting a [discussion](https://docs.github.com/en/discussions) to see if there's interest in what you want to do.**
 - **Submit PRs from feature branches on forks.**
 - **Ensure PRs pass all CI checks.**
-- **Maintain test coverage at 100%.**
+- **Maintain or increase test coverage.**
 
 ### Maintainers
 
-- **The default branch is `master`.**
-- **PRs should be merged into `master`.** Head branches are deleted automatically after PRs are merged.
-
-## Python
-
-### Poetry
-
-This project uses [Poetry](https://python-poetry.org/) for dependency management.
-
-#### Highlights
-
-- **Automatic dependency management:** rather than having to run `pip freeze > requirements.txt`, Poetry automatically manages the dependency file (called _pyproject.toml_), and enables SemVer-level control over dependencies like [npm](https://semver.npmjs.com/) does.
-- **Separation of development and production dependencies**: Poetry can maintain separate lists of dependencies for development and production in the _pyproject.toml_. Production installs can skip development dependencies to speed up Docker builds.
-- **Dependency resolution:** Poetry will automatically resolve any dependency version conflicts. As explained in the [pip docs](https://pip.pypa.io/en/latest/user_guide/#requirements-files) and [pypa/pip#988](https://github.com/pypa/pip/issues/988) (open since 2013), pip does not have dependency resolution. PSF has funded an [effort](https://www.pythonpodcast.com/pip-resolver-dependency-management-episode-264/) to improve pip dependency resolution.
-- **Lockfile:** similar to _package-lock.json_, Poetry will automatically track specific versions and hashes for every dependency.
-- **Builds:** Poetry has features for easily building the application.
-
-#### Installation
-
-The recommended installation method is through the [Poetry custom installer](https://python-poetry.org/docs/#installation), which vendorizes dependencies into an isolated environment, and allows you to update Poetry with `poetry self update`:
-
-```sh
-# osx / linux / bashonwindows install instructions
-curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -
-
-# windows powershell install instructions
-(Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py -UseBasicParsing).Content | python -
-```
-
-You can also install Poetry however you prefer to install your user Python packages (`pipx install poetry`, `pip install --user poetry`, etc). Use the standard update methods with these tools (`pipx upgrade poetry`, `pip install --user --upgrade poetry`, etc).
-
-#### Key commands
-
-```sh
-# Basic usage: https://python-poetry.org/docs/basic-usage/
-# install virtual environment, like python3 -m venv venv or virtualenv virtual
-# also installs dependencies, like pip install -r requirements.txt
-poetry install
-
-# list installed packages
-poetry show --tree
-
-# add a package, like pip install package (add --dev for dev-only install)
-poetry add PACKAGE
-
-# update dependencies (not available with standard tools)
-poetry update
+- **Make `develop` the default branch.**
+- **Merge PRs into `develop`.** Configure repository settings so that branches are deleted automatically after PRs are merged.
+- **Only merge to `main` if [fast-forwarding](https://www.git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging) from `develop`.**
+- **Enable [branch protection](https://docs.github.com/en/free-pro-team@latest/github/administering-a-repository/about-protected-branches) on `develop` and `main`.**
+- **Set up a release workflow.** Here's an example release workflow, controlled by Git tags:
+  - Bump the version number in `pyproject.toml` with `poetry version` and commit the changes to `develop`.
+  - Push to `develop` and verify all CI checks pass.
+  - Fast-forward merge to `main`, push, and verify all CI checks pass.
+  - Create an [annotated and signed Git tag](https://www.git-scm.com/book/en/v2/Git-Basics-Tagging)
+    - Follow [SemVer](https://semver.org/) guidelines when choosing a version number.
+    - List PRs and commits in the tag message:
+      ```sh
+      git log --pretty=format:"- %s (%h)" "$(git describe --abbrev=0 --tags)"..HEAD
+      ```
+    - Omit the leading `v` (use `1.0.0` instead of `v1.0.0`)
+    - Example: `git tag -a -s 1.0.0`
+  - Push the tag. GitHub Actions will build and push the Python package and Docker images.
 
-# activate the virtual environment, like source venv/bin/activate
-poetry shell
-
-# run a command within the virtual environment
-poetry run COMMAND
-
-# manage environments: https://python-poetry.org/docs/managing-environments/
-poetry env info
+## Git
 
-# configure your Poetry installation to install virtualenvs into .venv
-poetry config virtualenvs.in-project true
+- _[Why use Git?](https://www.git-scm.com/about)_ Git enables creation of multiple versions of a code repository called branches, with the ability to track and undo changes in detail.
+- Install Git by [downloading](https://www.git-scm.com/downloads) from the website, or with a package manager like [Homebrew](https://brew.sh/).
+- [Configure Git to connect to GitHub with SSH](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/connecting-to-github-with-ssh)
+- [Fork](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/fork-a-repo) this repo
+- Create a [branch](https://www.git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) in your fork.
+- Commit your changes with a [properly-formatted Git commit message](https://chris.beams.io/posts/git-commit/).
+- Create a [pull request (PR)](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/about-pull-requests) to incorporate your changes into the upstream project you forked.
 
-# export dependencies to requirements.txt
-poetry export -f requirements.txt > requirements.txt --dev
-```
+## Python
 
-### Code style
+### Python code style
 
-- Python code is formatted with [Black](https://black.readthedocs.io/en/stable/). Configuration for Black is stored in _[pyproject.toml](pyproject.toml)_.
+- Python code is formatted with [Black](https://black.readthedocs.io/en/stable/). Configuration for Black is stored in _pyproject.toml_.
 - Python imports are organized automatically with [isort](https://pycqa.github.io/isort/).
   - The isort package organizes imports in three sections:
     1. Standard library
     2. Dependencies
     3. Project
   - Within each of those groups, `import` statements occur first, then `from` statements, in alphabetical order.
   - You can run isort from the command line with `poetry run isort .`.
-  - Configuration for isort is stored in _[pyproject.toml](pyproject.toml)_.
+  - Configuration for isort is stored in _pyproject.toml_.
 - Other web code (JSON, Markdown, YAML) is formatted with [Prettier](https://prettier.io/).
 - Code style is enforced with [pre-commit](https://pre-commit.com/), which runs [Git hooks](https://www.git-scm.com/book/en/v2/Customizing-Git-Git-Hooks).
 
-  - Configuration is stored in _[.pre-commit-config.yaml](../.pre-commit-config.yaml)_.
+  - Configuration is stored in _.pre-commit-config.yaml_.
   - Pre-commit can run locally before each commit (hence "pre-commit"), or on different Git events like `pre-push`.
   - Pre-commit is installed in the Poetry environment. To use:
 
@@ -129,15 +86,50 @@ poetry export -f requirements.txt > requirements.txt --dev
     .venv ❯ pre-commit install --hook-type pre-push
     ```
 
-  - Pre-commit is also useful as a CI tool. The [hooks](.github/workflows/hooks.yml) GitHub Actions workflow runs pre-commit hooks with [GitHub Actions](https://github.com/features/actions).
+  - Pre-commit is also useful as a CI tool. The GitHub Actions workflows run pre-commit hooks with [GitHub Actions](https://github.com/features/actions).
+
+### Poetry
+
+This project uses [Poetry](https://python-poetry.org/) for dependency management.
+
+#### Highlights
+
+- **Automatic virtual environment management**: Poetry automatically manages the `virtualenv` for the application.
+- **Automatic dependency management**: rather than having to run `pip freeze > requirements.txt`, Poetry automatically manages the dependency file (called _pyproject.toml_), and enables SemVer-level control over dependencies like [npm](https://semver.npmjs.com/). Poetry also manages a lockfile (called _poetry.lock_), which is similar to _package-lock.json_ for npm. Poetry uses this lockfile to automatically track specific versions and hashes for every dependency.
+- **Dependency resolution**: Poetry will automatically resolve any dependency version conflicts. pip did not have dependency resolution [until the end of 2020](https://pip.pypa.io/en/latest/user_guide/#changes-to-the-pip-dependency-resolver-in-20-3-2020).
+- **Dependency separation**: Poetry can maintain separate lists of dependencies for development and production in the _pyproject.toml_. Production installs can skip development dependencies to speed up Docker builds.
+- **Builds**: Poetry has features for easily building the project into a Python package.
+
+#### Installation
+
+The recommended installation method is through the [Poetry custom installer](https://python-poetry.org/docs/#installation), which vendorizes dependencies into an isolated environment, and allows you to update Poetry with `poetry self update`.
+
+You can also install Poetry however you prefer to install your user Python packages (`pipx install poetry`, `pip install --user poetry`, etc). Use the standard update methods with these tools (`pipx upgrade poetry`, `pip install --user --upgrade poetry`, etc).
+
+#### Key commands
+
+```sh
+# Basic usage: https://python-poetry.org/docs/basic-usage/
+poetry install  # create virtual environment and install dependencies
+poetry show --tree  # list installed packages
+poetry add PACKAGE@VERSION # add a package to production dependencies, like pip install
+poetry add PACKAGE@VERSION --dev # add a package to development dependencies
+poetry update  # update dependencies (not available with standard tools)
+poetry version  # list or update version of this package
+poetry shell  # activate the virtual environment, like source venv/bin/activate
+poetry run COMMAND  # run a command within the virtual environment
+poetry env info  # manage environments: https://python-poetry.org/docs/managing-environments/
+poetry config virtualenvs.in-project true  # configure Poetry to install virtualenvs into .venv
+poetry export -f requirements.txt > requirements.txt --dev  # export dependencies
+```
 
 ## Docker
 
 - **[Docker](https://www.docker.com/)** is a technology for running lightweight virtual machines called **containers**.
   - An **image** is the executable set of files read by Docker.
   - A **container** is a running image.
   - The **[Dockerfile](https://docs.docker.com/engine/reference/builder/)** tells Docker how to build the container.
-- To install Docker tools locally:
+- To [get started with Docker](https://www.docker.com/get-started):
   - Ubuntu Linux: follow the [instructions for Ubuntu Linux](https://docs.docker.com/install/linux/docker-ce/ubuntu/), making sure to follow the [postinstallation steps](https://docs.docker.com/install/linux/linux-postinstall/) to activate the Docker daemon.
   - macOS and Windows: install [Docker Desktop](https://www.docker.com/products/docker-desktop) (available via [Homebrew](https://brew.sh/) with `brew cask install docker`).
 - <details><summary>Expand this details element for more <a href="https://docs.docker.com/engine/reference/commandline/cli/">useful Docker commands</a>.</summary>