From 9cfb8679af67411044d7520d00dced8b095052f8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Niko=20F=C3=B6hr?= <fohrloop@gmail.com>
Date: Sun, 26 May 2024 20:46:18 +0300
Subject: [PATCH] Update dev docs: how to deploy + testing options (#308)

Closes: #295

Developer documentation
-----------------------
* Add steps on how to create a release
* Update documentation about testing options
---
 DEV.md | 55 +++++++++++++++++++++----------------------------------
 1 file changed, 21 insertions(+), 34 deletions(-)

diff --git a/DEV.md b/DEV.md
index 5f463ffd..097c041d 100644
--- a/DEV.md
+++ b/DEV.md
@@ -41,7 +41,15 @@ invoke docs
 
 # Testing
 
-Wakepy uses pytest for testing the source tree with one python version and tox for testing the created wheel with multiple python versions.
+Wakepy uses pytest for testing the source tree with one python version and tox for testing the created wheel with multiple python versions. The test commands from smallest to largest iteration cycle:
+
+- `python -m pytest /tests/unit/some.py::somefunc` - Run a single test on single python version. Tests against source tree.
+- `python -m pytest ` - Run all unit and integration tests on single python version. Tests against source tree.
+- `inv test` (`invoke test`) - pytest + black + isort + ruff + mypy checks on single python version. Tests against source tree.
+- `tox` - pytest on multiple python versions & black + isort + ruff + mypy on single python version. Tests are run agains a build (.whl) version instead of the source tree.
+- GitHub Actions (PR checks): pytest + mypy on multiple python versions and multiple operating systems. Code check (isort + black + ruff + mypy) on single python version. Test that documentation build does not crash.
+
+Below a few more words about the `inv test` and `tox` options.
 
 ## Running tests with single environment
 
@@ -74,38 +82,17 @@ tox -e py310 -- --pdb
 
 - When using tox within this project, what happens is (1) wakepy is built with `python -m build`. This creates sdist from source tree and then wheel from the sdist. (2) Tests are ran against the created *wheel* (if not `skip_install=True` for that environment).
 
-# Deployment
-
-- Create a wheel with
-
-```
-python -m pip wheel --no-deps .
-```
-- Push to PyPI  (assuming the one-time setup below done)
-```
-python -m twine  upload wakepy-<version>-py3-none-any.whl --repository wakepy
-```
-- If made a new version, remember to update the `main` branch so ReadTheDocs may update the documentation.
-- Also, check that readthedocs has included all the correct versions (git tags)
-
+# Creating a release
 
-## Setting up twine/pip for uploading to PyPI
-- This should be done once per system
-- (1) Get a PyPI token for the *project* from [pypi.org/manage/account/token/](https://pypi.org/manage/account/token/)
-- (2) Create a `$HOME/.pypirc` file with following contents:
+The release process is automated, but changelog creation takes a few manual steps, since then it's possible to use Sphinx syntax to refer and link to python classes, methods and attributes within the changelog, and it's possible to get the same changelog to RTD and GitHub Releases.
 
-```
-[distutils]
-  index-servers =
-    pypi
-    wakepy
-
-[pypi]
-  username = __token__
-  password = # either a user-scoped token or a project-scoped token you want to set as the default
-
-[wakepy]
-  repository = https://upload.pypi.org/legacy/
-  username = __token__
-  password = # the wakepy project scoped token here.
-```
\ No newline at end of file
+**Steps**:
+- Add changelog and release date to [changelog.md](docs/source/changelog.md)
+- Merge the changes to main.
+- Locally, fetch and checkout latest main, and create a new git tag with format "vX.Y.X"
+- Push the tag to GitHub. Verify that the tag commit is same as latest main commit.
+- Go to GitHub and run the action for release (https://github.com/fohrloop/wakepy/actions/workflows/publish-a-release.yml) on the "main" branch.
+- After release, go to GitHub Releases at https://github.com/fohrloop/wakepy/releases/tag/main. Start editing the description of the latest release.
+- Copy-paste the changelog from https://wakepy.readthedocs.io/stable/changelog.html to the description. Add titles (`###`)  and list markers (`-`) back.
+- Copy-paste the text further to a text editor and find and replace "wakepy.readthedocs.io/stable" with "wakepy.readthedocs.io/X.Y.Z" to keep the changelog links working even after later releases.
+- Copy-paste back to the GitHub Releases, and save with title "wakepy X.Y.Z"
\ No newline at end of file