simplex-chat/docs/contributing/RELEASES.md

Library and package releases

Releases

Release	Location	Version	Published on
libsimplex	simplex-chat-libs release core-<version>	version of simplex-chat.cabal	push to master or stable with a new core version
Node.js add-on	simplex-chat-libs release nodejs-addon-<7 characters of the commit>		push to master or stable with unreleased add-on sources
@simplex-chat/types	npm	version of packages/simplex-chat-client/types/typescript/package.json	library release with an unpublished types version
simplex-chat	npm	version of packages/simplex-chat-nodejs/package.json	push to master or stable with an unpublished version
simplex-chat	PyPI	__version__ of packages/simplex-chat-python/src/simplex_chat/_version.py	push to master or stable with an unpublished version

Add-on sources:

• packages/simplex-chat-nodejs/binding.gyp
• packages/simplex-chat-nodejs/cpp/
• node-addon-api version in devDependencies of packages/simplex-chat-nodejs/package.json

Release states in simplex-chat-libs:

draft       created by maybe-release; assets uploaded by the build jobs
published   every asset present; published by the releases job

npm tag: beta for a version with a prerelease part, latest otherwise.

Releases and publications are independent of the Haskell test results.

releases.toml of simplex-chat-libs, written by build.yml:

core.<branch>.<version>     commit of the library release; branch: master or stable
npm.<package>.<version>     commit of the publication
pypi.<package>.<version>    commit of the publication

Library release

1. On master or stable, after git pull:

   python3 scripts/ci/packages_release.py core-release <version>
   

   Checked: version higher than the highest version recorded for the branch.

   Written:

   • version of simplex-chat.cabal
   • with types changed since the previous library release of the branch: types version (bumped), simplexChatCore, line SimpleX Chat core: of the types README

   --types-version sets the types version, for the first release of an app version, e.g. --types-version 7.1.0-beta.7.1.

2. Commit, push to the same branch.

3. Run of build.yml:

   • maybe-release: version claimed for the commit in releases.toml, draft core-<version> created
   • build jobs: 6 library zips uploaded; macOS libraries signed with the Developer ID and notarized
   • releases: release published
   • publish: @simplex-chat/types published, when its version is unpublished
   • record: types version recorded

Failed claim, with every build job skipped:

• version lower than the highest version recorded for the branch
• types changed, types version published
• types changed, simplexChatCore different from the core version

After a failed claim, a fix commit is pushed; the version is claimed by the next push.

Incomplete draft: completed by a re-run of the failed jobs in the run of the claim. The version is skipped by later pushes, as it is recorded for another commit.

Add-on release

Run of build.yml on a push to master or stable with unreleased add-on sources:

• maybe-release: draft nodejs-addon-<7 characters of the commit> created, notes sources: <hash of the add-on sources>
• build jobs, 5 platforms: add-on built, tested with the latest library release of the branch, uploaded
• releases: release published

Incomplete draft: completed by a re-run or by the next push with the same add-on sources.

Package release

1. On master or stable, after git pull:

   python3 scripts/ci/packages_release.py prepare [nodejs] [python]
   

   Both packages when none is listed.

   Checked:

   • published library release recorded for the branch
   • add-on release published with every asset (Node.js)
   • types version published on npm (Node.js)
   • Python types unchanged since the commit of the pinned library release (Python)
   • pinned releases published with the pinned SHA-256
   • every pinned asset downloaded with a matching SHA-256

   Written:

   • pins in packages/simplex-chat-nodejs/src/release.ts and _version.py: latest library release of the branch, add-on release of the current sources (Node.js), SHA-256 of every asset
   • @simplex-chat/types dependency: ^<types version> (Node.js)
   • package versions: a published version bumped when the pins or the package files changed

   --nodejs-version and --python-version set the versions, for the first release of an app version, e.g. --nodejs-version 7.1.0-beta.7.1 --python-version 7.1.0b7.

2. Commit, push to the same branch.

3. Run of build.yml:

   • build jobs, 5 platforms: packages tested, Node.js with the pinned add-on
   • publish: package tests of 5 platforms and pins checked, unpublished versions published with trusted publishing
   • record: published versions recorded

Versions unpublished after a failure: published by the next push to the branch.

Local publication

1. Step 1 of the package release.

2. Package tests in a Python virtual environment, on the local platform (linux-x86_64, linux-aarch64, macos-aarch64, macos-x86_64 or windows-x86_64):

   scripts/ci/package-tests.sh publish <platform> nodejs python
   

3. In packages/simplex-chat-nodejs, with the npm tag of the version:

   npm publish --access public --tag beta
   

4. In packages/simplex-chat-python:

   python -m pip install build twine
   python -m build
   twine upload dist/simplex_chat-<version>*
   

5. Commit, push to the same branch. Locally published versions are skipped by build.yml and are not recorded in releases.toml.

Settings

• simplex-chat-libs: release immutability enabled
• secret NODEJS_REPO_TOKEN: contents of simplex-chat-libs, read and write
• secrets APPLE_SIMPLEX_SIGNING_KEYCHAIN, APPLE_SIMPLEX_NOTARIZATION_APPLE_ID and APPLE_SIMPLEX_NOTARIZATION_PASSWORD: signing and notarization of the macOS libraries, shared with the desktop app build
• trusted publisher of simplex-chat and @simplex-chat/types on npm and of simplex-chat on PyPI: workflow build.yml
• secrets NPM_TOKEN and PYPI_API_TOKEN: used instead of trusted publishing when set
• variables NPM_SCOPE, PYPI_PROJECT, PYPI_URL and PYPI_UPLOAD_URL: publication under other names, for test repositories

Pull requests

• packages.yml, for package changes:
  • core unchanged: add-on built and packages tested on 5 platforms
  • core changed: add-on built on 5 platforms when its sources changed
• build.yml, for core changes: package tests on Linux x86_64 with the library built from the pull request