diff --git a/.github/dependabot.yaml b/.github/dependabot.yaml new file mode 100644 index 0000000..bf006b2 --- /dev/null +++ b/.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 diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml new file mode 100644 index 0000000..9c25c66 --- /dev/null +++ b/.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 }} diff --git a/.gitignore b/.gitignore index a94313a..d2f7d2c 100644 --- a/.gitignore +++ b/.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 diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..825c32f --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1 @@ +# Changelog diff --git a/DEV.md b/DEV.md new file mode 100644 index 0000000..f701445 --- /dev/null +++ b/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 +``` diff --git a/DEV.rst b/DEV.rst deleted file mode 100644 index 611939a..0000000 --- a/DEV.rst +++ /dev/null @@ -1,34 +0,0 @@ -================================================ -Jupyter Launcher Shortcuts development & release -================================================ - -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 -``` - -Create dist packages -==================== - -``` -hatch build -``` - - -Increase minor version -====================== - -``` -hatch minor version -hatch build -``` \ No newline at end of file diff --git a/README.rst b/README.md similarity index 58% rename from README.rst rename to README.md index ba1286f..83188a3 100644 --- a/README.rst +++ b/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`_) @@ -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' + } +} +``` diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 0000000..af77bcc --- /dev/null +++ b/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 diff --git a/jupyter_launcher_shortcuts/_version.py b/jupyter_launcher_shortcuts/_version.py new file mode 100644 index 0000000..2f2a30f --- /dev/null +++ b/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" diff --git a/pyproject.toml b/pyproject.toml index 89dc8e2..7b5e5ab 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,8 @@ build-backend = "hatchling.build" [project] name = "jupyter-launcher-shortcuts" -readme = "README.rst" +version = "4.0.0-0.dev" +readme = "README.md" license = { file = "LICENSE" } requires-python = ">=3.8" classifiers = [ @@ -28,28 +29,34 @@ dependencies = [ "tornado", "traitlets", ] -dynamic = ["version", "description", "authors", "urls", "keywords"] - -[tool.hatch.version] -source = "nodejs" - -[tool.hatch.metadata.hooks.nodejs] -fields = ["description", "authors", "urls"] +dynamic = ["description", "authors", "urls", "keywords"] [tool.hatch.build.targets.sdist] artifacts = ["jupyter_launcher_shortcuts/labextension"] -exclude = [".github", "binder"] +exclude = [".github"] [tool.hatch.build.targets.wheel.shared-data] "jupyter_launcher_shortcuts/labextension" = "share/jupyter/labextensions/jupyter_launcher_shortcuts" "install.json" = "share/jupyter/labextensions/jupyter_launcher_shortcuts/install.json" "jupyter_launcher_shortcuts/etc/serverextension.json" = "etc/jupyter/jupyter_server_config.d/jupyter_launcher_shortcuts.json" -[tool.hatch.build.hooks.version] -path = "jupyter_launcher_shortcuts/_version.py" +# hatch-nodejs-version is used to populate information in pyproject.toml +# dynamically based on information in package.json +# +# ref: https://github.com/agoose77/hatch-nodejs-version#readme +# +[tool.hatch.metadata.hooks.nodejs] +fields = ["description", "authors", "urls"] + + +# jupyter-builder is used to ensure we build the jupyterlab extension when the +# Python package is built +# +# ref: https://github.com/jupyterlab/hatch-jupyter-builder#readme +# [tool.hatch.build.hooks.jupyter-builder] -dependencies = ["hatch-jupyter-builder>=0.5"] +dependencies = ["hatch-jupyter-builder>=0.9.1"] build-function = "hatch_jupyter_builder.npm_builder" ensured-targets = [ "jupyter_launcher_shortcuts/labextension/static/style.js", @@ -67,6 +74,11 @@ npm = ["jlpm"] source_dir = "src" build_dir = "jupyter_launcher_shortcuts/labextension" + +# jupyter-releaser isn't confirmed to be used in this project, is it? +# +# ref: https://github.com/jupyter-server/jupyter_releaser#readme +# [tool.jupyter-releaser.options] version_cmd = "hatch version" @@ -78,5 +90,45 @@ before-build-npm = [ ] before-build-python = ["jlpm clean:all"] + +# check-wheel-contents isn't confirmed to be used in this project, is it? +# +# ref: https://github.com/jwodder/check-wheel-contents#readme +# [tool.check-wheel-contents] ignore = ["W002"] + + +# 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/2i2c-org/jupyter-launcher-shortcuts" + +[tool.tbump.version] +current = "4.0.0-0.dev" +regex = ''' + (?P\d+) + \. + (?P\d+) + \. + (?P\d+) + -? + (?P
((alpha|beta|rc)\.\d+)|)
+    (?P(0\.dev)|)
+'''
+
+[tool.tbump.git]
+message_template = "Bump to {new_version}"
+tag_template = "v{new_version}"
+
+[[tool.tbump.file]]
+src = "jupyter_launcher_shortcuts/_version.py"
+
+[[tool.tbump.file]]
+src = "pyproject.toml"
+
+[[tool.tbump.file]]
+src = "package.json"