onionshare/RELEASE.md

OnionShare Release Process

Unless you're a core OnionShare developer making a release, you'll probably never need to follow it.

Changelog, version, docs, and signed git tag

Before making a release, you must update the version in these places:

• cli/pyproject.toml
• cli/setup.py
• cli/onionshare_cli/resources/version.txt
• desktop/pyproject.toml (under version and the ./onionshare_cli-$VERSION-py3-none-any.whl dependency)
• desktop/src/setup.py
• docs/source/conf.py

You also must edit these files:

• desktop/install/org.onionshare.OnionShare.appdata.xml should have the correct release date, and links to correct screenshots
• Update all of the documentation in docs to cover new features, including taking new screenshots if necessary.
• In snap/snapcraft.yaml, the tor, libevent, and obfs4 parts should be updated if necessary, and all python packages should be updated to match cli/pyproject.toml and desktop/pyproject.toml
• CHANGELOG.md should be updated to include a list of all major changes since the last release
• There must be a PGP-signed git tag for the version, e.g. for OnionShare 2.1, the tag must be v2.1

The first step for the Linux, macOS, and Windows releases is the same.

Verify the release git tag:

git fetch
git tag -v v$VERSION

If the tag verifies successfully, check it out:

git checkout v$VERSION

PyPi release

The CLI version of OnionShare gets published on PyPi. To make a release:

cd cli
poetry install
poetry publish --build

Linux Flatpak release

See instructions for the Flatpak release here: https://github.com/micahflee/org.onionshare.OnionShare

Linux Snapcraft release

You must have snap and snapcraft (snap install snapcraft --classic) installed.

Build and test the snap before publishing:

snapcraft
snap install --devmode ./onionshare_*.snap

Run the OnionShare snap:

/snap/bin/onionshare     # GUI version
/snap/bin/onionshare.cli # CLI version

Linux AppImage release

Note: AppImage packages are currently broken due to this briefcase bug. Until it's fixed, OnionShare for Linux will only be available in Flatpak and Snapcraft.

Build a wheel package for OnionShare CLI:

cd cli
poetry install
poetry build

This will make a file like dist/onionshare_cli-$VERSION-py3-none-any.whl (except with your specific version number). Move it into ../desktop/linux:

mkdir -p ../desktop/linux
mv dist/onionshare_cli-*-py3-none-any.whl ../desktop/linux
# change back to the desktop directory
cd ../desktop

Make sure the virtual environment is active, and then run briefcase create and briefcase build:

. venv/bin/activate
briefcase create
briefcase build

Windows

Set up the development environment described in README.md. And install the Windows 10 SDK and add C:\Program Files (x86)\Windows Kits\10\bin\10.0.19041.0\x86 to your path.

Make sure your virtual environment is active:

venv\Scripts\activate.bat

Run the Windows build script:

python package\windows\build.py

This will create windows/OnionShare-$VERSION.msi, signed.

macOS

Set up the development environment described in README.md. And install create-dmg:

brew install create-dmg

Make sure your virtual environment is active:

. venv/bin/activate

Run the macOS build script:

./package/macos/build.py --with-codesign

Now, notarize the release. You must have an app-specific Apple ID password saved in the login keychain called onionshare-notarize.

• Notarize it: xcrun altool --notarize-app --primary-bundle-id "com.micahflee.onionshare" -u "micah@micahflee.com" -p "@keychain:onionshare-notarize" --file macOS/OnionShare.dmg
• Wait for it to get approved, check status with: xcrun altool --notarization-history 0 -u "micah@micahflee.com" -p "@keychain:onionshare-notarize"
• After it's approved, staple the ticket: xcrun stapler staple macOS/OnionShare.dmg

This will create macOS/OnionShare.dmg, signed and notarized.

Source package

TODO: Write documentation for source package

Publishing the release

To publish the release:

• Create a new release on GitHub, put the changelog in the description of the release, and upload all six files (the macOS installer, the Windows installer, the source package, and their signatures)
• Upload the six release files to https://onionshare.org/dist/$VERSION/
• Copy the six release files into the OnionShare team Keybase filesystem
• Update the onionshare-website repo:
  • Edit latest-version.txt to match the latest version
  • Update the version number and download links
  • Deploy to https://onionshare.org/
• Email the onionshare-dev mailing list announcing the release
• Make a PR to homebrew-cask to update the macOS version