Merge pull request #353 from consideRatio/pr/refine-release-md-with-tbump

Refine RELEASE.md with tbump

Author: consideRatio

RELEASE.md

@@ -1,87 +1,64 @@
 # How to make a release
 
-`jupyter-server-proxy` is a package [available on
-PyPI](https://pypi.org/project/jupyter-server-proxy/) and
-[conda-forge](https://github.com/conda-forge/jupyter-server-proxy-feedstock).
-These are instructions on how to make a release on PyPI. The PyPI release is
-done automatically by [GitHub
-Actions](https://github.com/jupyterhub/jupyter-server-proxy/actions/workflows/publish.yaml)
-when a tag is pushed.
+`jupyter-server-proxy` is a package available on [PyPI][] and [conda-forge][].
+These are instructions on how to make a release.
 
-For you to follow along according to these instructions, you need:
+## Pre-requisites
 
-- To have push rights to the [jupyter-server-proxy GitHub
-  repository](https://github.com/jupyterhub/jupyter-server-proxy).
+- Push rights to [github.com/jupyterhub/jupyter-server-proxy][]
+- Push rights to [conda-forge/jupyter-server-proxy-feedstock][]
 
-## Steps to make before a release
+## Steps to make a release
 
-1. Consider updating jupyterlab-server-proxy/yarl.lock to avoid a build
-   environment with potential known vulnerabilities. At least check in at
-   https://github.com/jupyterhub/jupyter-server-proxy/security/dependabot to
-   make sure no known vulnerabilities are listed.
+1. Create a PR updating `jupyterlab-server-proxy/yarl.lock` and continue only
+   when its merged.
 
-   If you want to update jupyterlab-server-proxy/yarl.lock, you can do so by
-   deleting the file and doing the first step of the GitHub workflow we have
-   defined to publish the PyPI package and the NPM package.
+   This helps us avoid leaving known vulnerabilities are unfixed. To do this,
+   delete the file and manually perform the the `build dist` step in the
+   `.github/workflows/publish.yaml` workflow's `build` job as summarized below.
 
    ```shell
-   pip install -U jupyter_packaging wheel "jupyterlab==3.*"
+   rm jupyterlab-server-proxy/yarn.lock
+
+   pip install jupyter_packaging wheel jupyterlab~=3.0
    python setup.py sdist bdist_wheel
    ```
 
-2. Update [changelog.md](docs/source/changelog.md). Doing this can be made
-   easier with the help of the
-   [executablebooks/github-activity](https://github.com/executablebooks/github-activity)
-   utility.
-
-## Steps to make a release
+2. Create a PR updating `docs/source/changelog.md` with [github-activity][] and
+   continue only when its merged.
 
-1. Checkout `main` and make sure it is up to date.
+3. Checkout main and make sure it is up to date.
 
    ```shell
-   ORIGIN=${ORIGIN:-origin} # set to the canonical remote, e.g. 'upstream' if 'origin' is not the official repo
    git checkout main
-   git fetch $ORIGIN main
-   git reset --hard $ORIGIN/main
-   # WARNING! This next command deletes any untracked files in the repo
-   git clean -xfd
+   git fetch origin main
+   git reset --hard origin/main
    ```
 
-1. Set the `version` variable in
-   [jupyterlab-server-proxy/package.json](jupyterlab-server-proxy/package.json)
-   appropriately and make a commit. Note that setup.py will read this from
-   jupyterlab-server-proxy/package.json.
-
-   ```
-   git add jupyterlab-server-proxy/package.json
-   VERSION=...  # e.g. 1.2.3
-   git commit -m "release v$VERSION"
-   ```
-
-2. Push your commit to main.
+4. Update the version, make commits, and push a git tag with `tbump`.
 
    ```shell
-   # first push commits without a tags to ensure the
-   # commits comes through, because a tag can otherwise
-   # be pushed all alone without company of rejected
-   # commits, and we want have our tagged release coupled
-   # with a specific commit in main
-   git push $ORIGIN main
-   ```
+   pip install tbump
+   tbump --dry-run ${VERSION}
 
-3. Create a git tag for the pushed release commit and push it.
+   # run
+   tbump ${VERSION}
+   ```
 
-   ```shell
-   git tag -a v$VERSION -m v$VERSION HEAD
+   Following this, the [CI system][] will build and publish a release.
 
-   # then verify you tagged the right commit
-   git log
+5. Reset the version back to dev, e.g. `4.0.1.dev0` after releasing `4.0.0`.
 
-   # then push it
-   git push $ORIGIN refs/tags/v$VERSION
+   ```shell
+   tbump --no-tag ${NEXT_VERSION}.dev0
    ```
 
-4. Following the release to PyPI, an automated PR should arrive to
-   [conda-forge/jupyter-server-proxy-feedstock](https://github.com/conda-forge/oauthenticator-feedstock),
-   check for the tests to succeed on this PR and then merge it to successfully
-   update the package for `conda` on the conda-forge channel.
+6. Following the release to PyPI, an automated PR should arrive to
+   [conda-forge/jupyter-server-proxy-feedstock][] with instructions.
+
+[github-activity]: https://github.com/executablebooks/github-activity
+[github.com/jupyterhub/jupyter-server-proxy]: https://github.com/jupyterhub/jupyter-server-proxy
+[pypi]: https://pypi.org/project/jupyter-server-proxy/
+[conda-forge]: https://anaconda.org/conda-forge/repo2docker_service
+[conda-forge/jupyter-server-proxy-feedstock]: https://github.com/conda-forge/jupyter-server-proxy-feedstock
+[ci system]: https://github.com/jupyterhub/jupyter-server-proxy/actions/workflows/release.yaml

pyproject.toml

@@ -1,3 +1,35 @@
+# build-system
+# - ref 1: https://peps.python.org/pep-0517/
+#
 [build-system]
 requires = ["jupyter_packaging~=0.7.9", "jupyterlab~=3.0", "setuptools>=40.8.0", "wheel"]
 build-backend = "setuptools.build_meta"
+
+
+# tbump is used to simplify and standardize the release process when updating
+# the version, making a git commit and tag, and pushing changes.
+#
+# ref: https://github.com/your-tools/tbump#readme
+#
+[tool.tbump]
+github_url = "https://github.com/jupyterhub/jupyter-server-proxy"
+
+[tool.tbump.version]
+current = "3.2.2"
+regex = '''
+    (?P<major>\d+)
+    \.
+    (?P<minor>\d+)
+    \.
+    (?P<patch>\d+)
+    (?P<pre>((a|b|rc)\d+)|)
+    \.?
+    (?P<dev>(?<=\.)dev\d*|)
+'''
+
+[tool.tbump.git]
+message_template = "Bump to {new_version}"
+tag_template = "v{new_version}"
+
+[[tool.tbump.file]]
+src = "jupyterlab-server-proxy/package.json"