Merge pull request #26 from consideRatio/pr/add-release-automation

Add release automation and related docs

.github/dependabot.yaml

@@ -0,0 +1,16 @@
+# dependabot.yaml reference: https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+#
+# Notes:
+# - Status and logs from dependabot are provided at
+#   https://github.com/2i2c-org/jupyter-launcher-shortcuts/network/updates.
+#
+version: 2
+updates:
+  # Maintain dependencies in our GitHub Workflows
+  - package-ecosystem: github-actions
+    directory: /
+    labels: [ci]
+    schedule:
+      interval: monthly
+      time: "05:00"
+      timezone: Etc/UTC

.github/workflows/release.yaml

@@ -0,0 +1,134 @@
+# This is a GitHub workflow defining a set of jobs with a set of steps.
+# ref: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions
+#
+# Publish PyPI and NPM artifacts
+#
+name: Release
+
+on:
+  pull_request:
+    paths-ignore:
+      - "**.md"
+      - ".github/workflows/*"
+      - "!.github/workflows/release.yaml"
+  push:
+    paths-ignore:
+      - "**.md"
+      - ".github/workflows/*"
+      - "!.github/workflows/release.yaml"
+    branches-ignore:
+      - "dependabot/**"
+      - "pre-commit-ci-update-config"
+    tags:
+      - "*"
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-22.04
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "lts/*"
+          registry-url: https://registry.npmjs.org
+
+      - name: Update root build packages
+        run: |
+          pip install --upgrade build pip
+
+      - name: Build dist
+        run: |
+          pyproject-build
+          cd dist && sha256sum * | tee SHA256SUMS
+
+      - name: Check dist sizes
+        run: |
+          set -eux
+          ls -lathr dist
+          [[ $(find dist -type f -size +200k) ]] && exit 1 || echo ok
+
+      - name: Javascript package
+        run: |
+          mkdir jsdist
+          cd jsdist
+          npm pack ../jupyter_launcher_shortcuts/labextension
+          sha256sum * | tee SHA256SUMS
+
+      - name: Upload Python artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist-${{ github.run_attempt }}
+          path: dist
+          if-no-files-found: error
+
+      - name: Upload Javascript artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: jsdist-${{ github.run_attempt }}
+          path: jsdist
+          if-no-files-found: error
+
+  # https://packaging.python.org/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/
+  publish-pypi:
+    runs-on: ubuntu-22.04
+    permissions:
+      id-token: write
+    needs:
+      - build
+
+    steps:
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Download artifacts from build
+        uses: actions/download-artifact@v4
+        with:
+          name: dist-${{ github.run_attempt }}
+          path: dist
+
+      # The PyPI publishing action will try to publish this checksum file as if
+      # it was a Python package if it remains in dist, so we clean it up first.
+      - name: Cleanup SHA256SUMS
+        run: |
+          cat dist/SHA256SUMS
+          rm dist/SHA256SUMS
+
+      - name: Publish to PyPI
+        if: startsWith(github.ref, 'refs/tags')
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_PASSWORD }}
+
+  # https://docs.github.com/en/actions/language-and-framework-guides/publishing-nodejs-packages#publishing-packages-to-the-npm-registry
+  publish-npm:
+    runs-on: ubuntu-22.04
+    needs:
+      - build
+
+    steps:
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "lts/*"
+
+      - name: Download artifacts from build
+        uses: actions/download-artifact@v4
+        with:
+          name: jsdist-${{ github.run_attempt }}
+          path: jsdist
+
+      - run: |
+          npm publish --dry-run ./jsdist/jupyter_launcher_shortcuts-*.tgz
+
+      - run: |
+          npm publish ./jsdist/jupyter_launcher_shortcuts-*.tgz
+        if: startsWith(github.ref, 'refs/tags')
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -7,9 +7,8 @@ node_modules/
 *.egg-info/
 .ipynb_checkpoints
 *.tsbuildinfo
+jsdist/
 jupyter_launcher_shortcuts/labextension
-# Version file is handled by hatchling
-jupyter_launcher_shortcuts/_version.py
 
 # Created by https://www.gitignore.io/api/python
 # Edit at https://www.gitignore.io/?templates=python

CHANGELOG.md

@@ -0,0 +1 @@
+# Changelog

DEV.md

@@ -0,0 +1,15 @@
+# Jupyter Launcher Shortcuts development
+
+## Pre-build labextension
+
+In order to rebuild Jupyterlab extension
+
+```
+micromamba create -n jupyterlab-ext --override-channels --strict-channel-priority -c conda-forge -c nodefaults jupyterlab=4 nodejs=18 git hatch jinja2-time
+micromamba activate jupyterlab-ext
+```
+
+Prebuild Jupyterlab extension
+```
+jlpm build
+```

README.rst → README.md

@@ -1,6 +1,4 @@
-==========================
-Jupyter Launcher Shortcuts
-==========================
+# Jupyter Launcher Shortcuts
 
 Extension for JupyterLab (version 4+) and classic Jupyter Notebook (version 7+,
 currently broken, see `Issue #25<https://github.com/2i2c-org/jupyter-launcher-shortcuts/issues/25>`_)
@@ -9,35 +7,33 @@ Binder situations.
 
 For JupyterLab, they're added in the launcher interface.
 
-.. image:: labextension.png
+![](labextension.png)
 
 For classic Jupyter Notebook, they are added under the 'New' button
 
-.. image:: nbextension.png
+![](nbextension.png)
 
-Installation
-============
+## Installation
 
 The JupyterLab extension, the classic Jupyter Notebook extension, and a Jupyter
 Server extension required behind the scenes can all be installed with ``pip``.
 
-.. code:: bash
+```bash
+pip install jupyter-launcher-shortcuts
+```
 
-   pip install jupyter-launcher-shortcuts
-
-Configuring
-===========
+## Configuring
 
 The extension can be configured in a ``jupyter_server_config.py``
 file created in any of the directories under ``config`` in the 
 output of ``jupyter --paths`` command.
 
-.. code:: python
-   
-   c.LauncherShortcuts.shortcuts = {
-       'my-shiny-application': {
-           'title': 'Human Readable Shortcut Title',
-           'target': '{base_url}shiny/my-shiny-application-directory/',
-           'icon_path': '/path/to/svg/file'
-       }
-   }
+```python
+c.LauncherShortcuts.shortcuts = {
+    'my-shiny-application': {
+        'title': 'Human Readable Shortcut Title',
+        'target': '{base_url}shiny/my-shiny-application-directory/',
+        'icon_path': '/path/to/svg/file'
+    }
+}
+```

RELEASE.md

@@ -0,0 +1,44 @@
+# How to make a release
+
+`jupyter-launcher-shortcuts` is a package available on [PyPI]. These are
+instructions on how to make a release.
+
+## Pre-requisites
+
+- Push rights to [github.com/2i2c-org/jupyter-launcher-shortcuts]
+
+## Steps to make a release
+
+1. Create a PR updating `CHANGELOG.md` with [github-activity] and continue only
+   when its merged.
+
+2. Checkout main and make sure it is up to date.
+
+   ```shell
+   git checkout main
+   git fetch origin main
+   git reset --hard origin/main
+   ```
+
+3. Update the version, make commits, and push a git tag with `tbump`.
+
+   ```shell
+   pip install tbump
+   tbump --dry-run ${VERSION}
+
+   # run
+   tbump ${VERSION}
+   ```
+
+   Following this, the [CI system] will build and publish a release.
+
+4. Reset the version back to dev, e.g. `4.0.1-0.dev` after releasing `4.0.0`.
+
+   ```shell
+   tbump --no-tag ${NEXT_VERSION}-0.dev
+   ```
+
+[github-activity]: https://github.com/executablebooks/github-activity
+[github.com/2i2c-org/jupyter-launcher-shortcuts]: https://github.com/2i2c-org/jupyter-launcher-shortcuts
+[pypi]: https://pypi.org/project/jupyter-launcher-shortcuts/
+[ci system]: https://github.com/2i2c-org/jupyter-launcher-shortcuts/actions/workflows/release.yaml

jupyter_launcher_shortcuts/_version.py

@@ -0,0 +1,4 @@
+# __version__ should be updated using tbump, based on configuration in
+# pyproject.toml, according to instructions in RELEASE.md.
+#
+__version__ = "4.0.0-0.dev"