Release

Tag-driven CLI + LSP multi-platform Nuitka binaries, wheels, Docker CLI image, VSIX packaging, GitHub Releases, and Marketplace publish.

This page

Release

Abstract

A PYNE release is a multi-artifact event, not a single wheel upload. The primary automation (.github/workflows/release.yml) builds:

  • PyPI sdist + wheel (hoox-pyne) with CLI smoke
  • CLI platform-native Nuitka binaries (pynescript)
  • LSP platform-native Nuitka binaries (pynescript-lsp)
  • CLI Docker image tarball (pynescript-cli-image.tar.gz)
  • VS Code VSIX

Assets attach to a GitHub Release; PyPI upload is handled by Publish (publish.yml). Multi-arch container images are a separate workflow (GHCR / ghcr.yml) — not attached as tarballs except the CLI image save in this workflow. Marketplace / Open VSX publish is optional via VSCE_PAT / OVSX_PAT.

Conceptual model

Diagram

Rendering…

Interface surface

Triggers

EventBehavior
Push tag matching v*Full build + create release + marketplace/Open VSX publish
workflow_dispatch with version inputSame jobs; Create Release also runs on dispatch (not tag-only)

Jobs

JobMatrix / OSOutput
build-packageubuntu-latesthoox-pyne-dist (sdist + wheel)
build-cliubuntu-latest, windows-latest, macos-latestpynescript-cli-linux-x86_64, …-windows-x86_64.exe, …-macos-arm64
build-lspubuntu-latest, windows-latest, macos-latestpynescript-lsp-linux-x86_64, …-windows-x86_64.exe, …-macos-arm64
build-docker-cliubuntu-latestpynescript-cli-docker (gzipped docker save)
build-vscodeubuntu-latestpynescript-vscode-extension VSIX
releaseneeds package + vscode success; tag or dispatchGitHub Release body + staged assets (name: pyne vX.Y.Z)
publish-vscodeneeds VSIX; tag or dispatchvsce publish if VSCE_PAT; ovsx publish if OVSX_PAT

Environment

env:
  PYTHON_VERSION: "3.11"   # Nuitka 2.5–2.7 graph; comment in workflow
  NUITKA_JOBS: 4

Build steps rely on:

# LSP
pip install -e ".[lsp]" "nuitka>=2.5.1,<2.8" cryptography
python scripts/build/compile.py --target lsp --no-encrypt --check
python scripts/build/ci_build.py --target lsp --jobs 4
# CRYPTO_KEY from secrets.METADATA_KEY

# CLI
pip install -e . "nuitka>=2.5.1,<2.8"
python scripts/build/compile.py --target cli --check
python scripts/build/ci_build.py --target cli --jobs 4 --skip-metadata --skip-vsix

Local make-side packaging

make package        # sdist + wheel (python -m build)
make build          # Nuitka LSP
make build-cli      # Nuitka CLI
make build-vscode   # npm install && compile && vsce package
make docker-build-cli

Artifacts land under dist/, dist/lsp/, dist/cli/, dist/vsix/, and vscode-extension/*.vsix depending on script path.

Internals

PathRole
.github/workflows/release.ymlOrchestration
scripts/build/ci_build.pyCI-oriented Nuitka + metadata encrypt
scripts/build/compile.pyLocal/full compile options (--onefile, --standalone, --check)
vscode-extension/package.jsonExtension version / engines
src/pynescript/__about__.pyHatch dynamic version for Python package

Release asset contract (from release body)

ArtifactInstall sketch
hoox_pyne-*.whl / *.tar.gzpip install ./hoox_pyne-*.whl
pynescript-cli-linux-x86_64chmod +x → /usr/local/bin/pynescript
pynescript-cli-windows-x86_64.exePlace on PATH as pynescript.exe
pynescript-cli-macos-arm64Place on PATH (Apple Silicon runners)
pynescript-cli-image.tar.gzgunzip -c … | docker load → pynescript-cli:latest
pynescript-lsp-linux-x86_64chmod +x → /usr/local/bin/pynescript-lsp
pynescript-lsp-windows-x86_64.exePlace on PATH
pynescript-lsp-macos-arm64Place on PATH (Apple Silicon runners)
pyne-vscode-*.vsix (hoox-sh.pyne 0.4.4)code --install-extension pyne-vscode-*.vsix · site: hoox.sh/pyne-vscode.vsix (unversioned)

Invariants & edge cases

  1. CRYPTO_KEY must be stable across builds if you care about byte-identical builtin_metadata.json.enc. Supply secrets.METADATA_KEY.
  2. Tag name is the version source for the GitHub Release title (v prefix stripped).
  3. Marketplace publish needs VSCE_PAT. Without it, packaging may still succeed while publish fails.
  4. Artifact retention is short (5 days on build jobs) — releases must attach files immediately.
  5. macOS artifact is ARM64 from macos-latest — Intel Mac users may need separate builds if required.
  6. Draft vs prerelease: workflow currently sets draft: false, prerelease: false for tag releases.

Worked examples

Cut a release

# ensure main is green
git checkout main && git pull
# bump versions in extension / __about__ as needed
git tag -a v0.3.14 -m "v0.3.14"
git push origin v0.3.14
# watch Actions → Build & Release, Publish, GHCR

Smoke-test a downloaded binary

chmod +x pynescript-cli-linux-x86_64
./pynescript-cli-linux-x86_64 --help
./pynescript-cli-linux-x86_64 check script.pine

chmod +x pynescript-lsp-linux-x86_64
./pynescript-lsp-linux-x86_64 --help
# or wire stdio into an editor client

Failure modes

SymptomCauseFix
Binary not found after NuitkaPath layout drift in ci_build.pyInspect dist/; fix finder step
Decrypt errors in fieldKey mismatch between encrypt and runtimeAlign METADATA_KEY with embedded key strategy
Empty GitHub Release assetsArtifact download path mismatchMatch files: globs to download-artifact layout
Marketplace 401Bad/expired VSCE_PATRotate PAT with Marketplace scopes
Windows .exe not marked executableFinder uses -type f -executableFallback non-executable find branch in workflow

See also