Update how-to guides (#443)

Author: blink1073

docs/source/how_to_guides/convert_repo_from_releaser.md

@@ -17,8 +17,10 @@ See checklist below for details:
 A. Prep the `jupyter_releaser` fork:
 
 - [ ] Clone this repository onto your GitHub user account.
-- [ ] Add a [GitHub Access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) with access to target GitHub repo to run GitHub Actions, saved as
-      `ADMIN_GITHUB_TOKEN` in the [repository secrets](https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository).
+- [ ] Add a GitHub [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) with access to target GitHub repo to run
+      GitHub Actions, saved as `ADMIN_GITHUB_TOKEN` in the
+      [repository secrets](https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository).
+      The token will need "public_repo", and "repo:status" permissions.
 - [ ] Add access token for the [PyPI registry](https://packaging.python.org/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/#saving-credentials-on-github) stored as `PYPI_TOKEN`.
       _Note_ For security reasons, it is recommended that you scope the access
       to a single repository, and use a variable called `PYPI_TOKEN_MAP` that is formatted as follows:
@@ -44,36 +46,42 @@ B. Prep target repository:
   - Can use `pandoc -s changelog.rst -o changelog.md` and some hand edits as needed.
   - Note that [directives](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#syntax-directives) can still be used
 - [ ] Add HTML start and end comment markers to Changelog file - see example in [CHANGELOG.md](https://github.com/jupyter-server/jupyter_releaser/blob/main/CHANGELOG.md) (view in raw mode)
-- [ ] Add [tbump](https://github.com/tankerhq/tbump) support if using Python - see example metadata in [pyproject.toml](https://github.com/jupyter-server/jupyter_releaser/blob/main/pyproject.toml)
-  - We recommend putting `setuptools` metadata in `setup.cfg` and using `version = attr: <package_name>.__version__`.
-  - See documentation on `setup.cfg` [metadata](https://setuptools.readthedocs.io/en/latest/userguide/declarative_config.html)
-  - If previously providing `version_info` like `version_info = (1, 7, 0, '.dev', '0')`, use tbump config like the one below:
+- [ ] We recommend using [hatch](https://hatch.pypa.io/latest/) for your
+      build system and for version handling.
+  - If previously providing `version_info` like `version_info = (1, 7, 0, '.dev', '0')`, use a pattern like the one below in your version file:
 
 ```toml
-[[tool.tbump.file]]
-src = "jupyter_server/_version.py"
-version_template = '({major}, {minor}, {patch}, "{channel}", "{release}")'
-
-[[tool.tbump.field]]
-name = "channel"
-default = ""
-
-[[tool.tbump.field]]
-name = "release"
-default = ""
+import re
+from typing import List
+
+# Version string must appear intact for hatch versioning
+__version__ = "6.16.0"
+
+# Build up version_info tuple for backwards compatibility
+pattern = r"(?P<major>\d+).(?P<minor>\d+).(?P<patch>\d+)(?P<rest>.*)"
+match = re.match(pattern, __version__)
+assert match is not None
+parts: List[object] = [int(match[part]) for part in ["major", "minor", "patch"]]
+if match["rest"]:
+    parts.append(match["rest"])
+version_info = tuple(parts)
 ```
 
+- If you need to keep node and python versions in sync, use [hatch-nodejs-version](https://github.com/agoose77/hatch-nodejs-version). See [nbformat](https://github.com/jupyter/nbformat/blob/main/pyproject.toml) for example.
+
 - [ ] Add a GitHub Actions CI step to run the `check_release` action. For example:
 
 ```yaml
 - name: Check Release
-  if: ${{ matrix.python-version == '3.9' }}
-  uses: jupyter-server/jupyter_releaser/.github/actions/check-release@v1
+  uses: jupyter-server/jupyter_releaser/.github/actions/check-release@v2
   with:
     token: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-_Note_ The check release action needs `contents: write` [permission](https://docs.github.com/en/actions/reference/authentication-in-a-workflow#modifying-the-permissions-for-the-github_token).
+- This should be run on `push` and `pull` request events. You can copy
+  the `check-release.yml` from this repo as an example. ${{ secrets.GITHUB_TOKEN }}
+
+````
 
 - [ ] If you would like the release assets to be uploaded as artifacts, add the following step after the `check_release` action:
 
@@ -83,12 +91,12 @@ _Note_ The check release action needs `contents: write` [permission](https://doc
   with:
     name: jupyter-releaser-dist-${{ github.run_number }}
     path: .jupyter_releaser_checkout/dist
-```
+````
 
 - [ ] Add a workflow that uses the [`enforce-label`](https://github.com/jupyterlab/maintainer-tools#enforce-labels) action from `jupyterlab/maintainer-tools` to ensure that all PRs have on of the triage labels used to
       categorize the changelog.
 
-- [ ] Update or add `RELEASE.md` that describes the onboarding and release process, e.g.
+- [ ] Update or add `RELEASE.md` that describes the onboarding and release process, e.g. [jupyter_server](https://github.com/jupyter-server/jupyter_server/blob/main/RELEASE.md).
 
 ## Release Workflow
 

docs/source/how_to_guides/convert_repo_from_repo.md

@@ -14,11 +14,18 @@ See [hecklist below for details:
 
 ## Checklist for Adoption
 
+- [ ] Add a GitHub [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token), preferably from a "machine user" GitHub
+      account that has write access to the repository. The token will need "public_repo", and "repo:status" permissions. Save the token as `ADMIN_GITHUB_TOKEN`
+      in the [repository secrets](https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository). We need this
+      access token to allow for branch protection rules, which block the pushing
+      of commits when using the `GITHUB_TOKEN`, even when run from an admin user
+      account.
 - [ ] Add access token for the [PyPI registry](https://packaging.python.org/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/#saving-credentials-on-github) stored as `PYPI_TOKEN`.
       _Note_ For security reasons, it is recommended that you scope the access
       to a single repository. Additionally, this token should belong to a
-      bot account and not a single user.
-- [ ] If needed, add access token for [npm](https://docs.npmjs.com/creating-and-viewing-access-tokens), saved as `NPM_TOKEN`.
+      machine account and not a user account.
+- [ ] If needed, add access token for [npm](https://docs.npmjs.com/creating-and-viewing-access-tokens), saved as `NPM_TOKEN`. Again this should
+      be created using a machine account that only has publish access.
 - [ ] Ensure that only trusted users with 2FA have admin access to the
       repository, since they will be able to trigger releases.
 - [ ] Switch to Markdown Changelog
@@ -47,17 +54,19 @@ if match["rest"]:
 version_info = tuple(parts)
 ```
 
+- If you need to keep node and python versions in sync, use [hatch-nodejs-version](https://github.com/agoose77/hatch-nodejs-version). See [nbformat](https://github.com/jupyter/nbformat/blob/main/pyproject.toml) for example.
+
 - [ ] Add a GitHub Actions CI step to run the `check_release` action. For example:
 
 ```yaml
 - name: Check Release
-  if: ${{ matrix.python-version == '3.9' }}
-  uses: jupyter-server/jupyter_releaser/.github/actions/check-release@v1
+  uses: jupyter-server/jupyter_releaser/.github/actions/check-release@v2
   with:
     token: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-_Note_ The check release action needs `contents: write` [permission](https://docs.github.com/en/actions/reference/authentication-in-a-workflow#modifying-the-permissions-for-the-github_token).
+- This should be run on `push` and `pull` request events. You can copy
+  the `check-release.yml` from this repo as an example.
 
 - [ ] If you would like the release assets to be uploaded as artifacts, add the following step after the `check_release` action:
 
@@ -72,7 +81,7 @@ _Note_ The check release action needs `contents: write` [permission](https://doc
 - [ ] Add a workflow that uses the [`enforce-label`](https://github.com/jupyterlab/maintainer-tools#enforce-labels) action from `jupyterlab/maintainer-tools` to ensure that all PRs have on of the triage labels used to
       categorize the changelog.
 
-- [ ] Update or add `RELEASE.md` that describes the onboarding and release process, e.g.
+- [ ] Update or add `RELEASE.md` that describes the onboarding and release process, e.g. [jupyter_server](https://github.com/jupyter-server/jupyter_server/blob/main/RELEASE.md).
 
 - [ ] Copy `prep-release.yml` and `publish-release.yml` from the `example-workflows` folder in this repository.
 

example-workflows/prep-release.yml

@@ -21,8 +21,6 @@ on:
         type: boolean
 jobs:
   prep_release:
-    permissions:
-      contents: write
     runs-on: ubuntu-latest
     steps:
       - uses: jupyterlab/maintainer-tools/.github/actions/base-setup@v1
@@ -31,7 +29,7 @@ jobs:
         id: prep-release
         uses: jupyter-server/jupyter_releaser/.github/actions/prep-release@v2
         with:
-          token: ${{ secrets.GITHUB_TOKEN }}
+          token: ${{ secrets.ADMIN_GITHUB_TOKEN }}
           version_spec: ${{ github.event.inputs.version_spec }}
           post_version_spec: ${{ github.event.inputs.post_version_spec }}
           target: ${{ github.event.inputs.target }}

example-workflows/publish-release.yml

@@ -15,16 +15,14 @@ on:
 jobs:
   publish_release:
     runs-on: ubuntu-latest
-    permissions:
-      contents: write
     steps:
       - uses: jupyterlab/maintainer-tools/.github/actions/base-setup@v1
 
       - name: Populate Release
         id: populate-release
         uses: jupyter-server/jupyter_releaser/.github/actions/populate-release@v2
         with:
-          token: ${{ secrets.GITHUB_TOKEN }}
+          token: ${{ secrets.ADMIN_GITHUB_TOKEN }}
           target: ${{ github.event.inputs.target }}
           branch: ${{ github.event.inputs.branch }}
           release_url: ${{ github.event.inputs.release_url }}
@@ -39,7 +37,7 @@ jobs:
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
         uses: jupyter-server/jupyter-releaser/.github/actions/finalize-release@v2
         with:
-          token: ${{ secrets.GITHUB_TOKEN }}
+          token: ${{ secrets.ADMIN_GITHUB_TOKEN }}
           target: ${{ github.event.inputs.target }}
           release_url: ${{ steps.populate-release.outputs.release_url }}