Document the release process (#363)

* Document release process

* Update changelog instructions w/ ref to keepachangelog

* Prettify bullet points

* Add docs deploy to release script

diff --git a/docs/contributing.md b/docs/contributing.md
index 15eadcd1c9b91b693429d4a37f5750b3bf0b8703..d44c03c39e7aaffc8e818fd4335a8ef453052a95 100644 (file)
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -114,3 +114,22 @@ To spawn the docs server run:
 ```shell
 $ mkdocs serve
 ```
+
+## Releasing
+
+*This section is targeted at HTTPX maintainers.*
+
+Before releasing a new version, create a pull request that includes:
+
+- **An update to the changelog**:
+    - We follow the format from [keepachangelog](https://keepachangelog.com/en/1.0.0/).
+    - [Compare](https://github.com/encode/httpx/compare/) `master` with the tag of the latest release, and list all entries that are of interest to our users:
+        - Things that **must** go in the changelog: added, changed, deprecated or removed features, and bug fixes.
+        - Things that **should not** go in the changelog: changes to documentation, tests or tooling.
+        - Try sorting entries in descending order of impact / importance.
+        - Keep it concise and to-the-point. 🎯
+- **A version bump**: see `__version__.py`.
+
+For an example, see [#362](https://github.com/encode/httpx/pull/362).
+
+Once the release PR is merged, run `$ scripts/publish` to publish the new release to PyPI.

diff --git a/scripts/publish b/scripts/publish
index 4fcc734cec020ccb636e0eb1d191303b4c6d2e63..16cbf689b43aa3aedf6025ce6390a644c932378e 100755 (executable)
--- a/scripts/publish
+++ b/scripts/publish
@@ -15,11 +15,18 @@ if ! command -v "${PREFIX}twine" &>/dev/null ; then
     exit 1
 fi
 
+if ! command -v "${PREFIX}mkdocs" &>/dev/null ; then
+    echo "Unable to find the 'mkdocs' command."
+    echo "Install from PyPI, using '${PREFIX}pip install mkdocs'."
+    exit 1
+fi
+
 find ${PACKAGE} -type f -name "*.py[co]" -delete
 find ${PACKAGE} -type d -name __pycache__ -delete
 
 ${PREFIX}python setup.py sdist
 ${PREFIX}twine upload dist/*
+${PREFIX}mkdocs gh-deploy
 
 echo "You probably want to also tag the version now:"
 echo "git tag -a ${VERSION} -m 'version ${VERSION}'"