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/onionshare_cli/resources/version.txt
• desktop/pyproject.toml
• desktop/setup.py
• desktop/org.onionshare.OnionShare.appdata.xml
• docs/source/conf.py (version at the top, and the versions list too)
• snap/snapcraft.yaml

If you update flask-socketio, ensure that you also update the socket.io.min.js file to a version that is supported by the updated version of flask-socketio.

Use tor binaries from the latest Tor Browser:

• desktop/scripts/get-tor-linux.py
• desktop/scripts/get-tor-osx.py
• desktop/scripts/get-tor-windows.py

Update the documentation:

• Update all of the documentation in docs to cover new features, including taking new screenshots if necessary

Finalize localization:

• Merge all the translations from weblate
• In docs run poetry run ./check-weblate.py [API_KEY] to see which translations are >90% in the app and docs
• Edit cli/onionshare_cli/settings.py, make sure self.available_locales lists only locales that are >90% translated
• From the desktop folder in the virtual env, run ./scripts/countries-update-list.py to make sure the localized country list for censorship circumvention is available in all available languages
• Edit docs/source/conf.py, make sure languages lists only languages that are >90% translated
• Edit docs/build.sh and make sure LOCALES= lists the same languages as above, in docs/source/conf.py
• Make sure the latest documentation is built and committed:

  cd docs
  poetry install
  poetry run ./build.sh
  

You also must edit these files:

• desktop/org.onionshare.OnionShare.appdata.xml should have the correct release date, and links to correct screenshots
• CHANGELOG.md should be updated to include a list of all major changes since the last release

Make sure snapcraft packaging works. In snap/snapcraft.yaml:

• The tor, libevent, and obfs4 parts should be updated if necessary
• All python packages in the onionshare part should be updated to match desktop/pyproject.toml
• Test the snap package, ensure it works

Finally:

• 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

Linux Snapcraft release

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

Build and test the snap before publishing (note that --dangerous lets you install the snap before it's codesigned):

snapcraft
snap install --dangerous ./onionshare_${VERSION}_amd64.snap

This will create onionshare_${VERSION}_amd64.snap.

Run the OnionShare snap locally:

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

Upload the to Snapcraft:

snapcraft login
snapcraft upload --release=stable onionshare_${VERSION}_amd64.snap

Windows

Set up the development environment described in desktop README.md.

• To get signtool.exe, install the Windows 10 SDK and add C:\Program Files (x86)\Windows Kits\10\bin\10.0.22000.0\x86 to your path.
• Go to https://dotnet.microsoft.com/download/dotnet-framework and download and install .NET Framework 3.5 SP1 Runtime. I downloaded dotnetfx35.exe.
• Go to https://wixtoolset.org/releases/ and download and install WiX toolset. I downloaded wix311.exe. Add C:\Program Files (x86)\WiX Toolset v3.11\bin to the path.

Build the Windows binaries, delete extra files, codesign, and create an MSI package:

poetry run python .\setup-freeze.py build
poetry run python .\package\windows.py cleanup-build
poetry run python .\package\windows.py codesign
poetry run python .\package\windows.py package

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

macOS

Set up the development environment described in README.md.

Then build an executable, make it a macOS app bundle, and package it in a dmg:

poetry run ./package/build-mac.py

The will create dist/OnionShare-$VERSION.dmg.

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 dist/OnionShare-$VERSION.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 dist/OnionShare-$VERSION.dmg

This will create desktop/dist/OnionShare-$VERSION.dmg, signed and notarized.

Source package

To make a source package, run ./build-source.sh $TAG, where $TAG is the name of the signed git tag, e.g. v2.1.

This will create dist/onionshare-$VERSION.tar.gz.

Publishing the release

PGP signatures

After following all of the previous steps, gather these files:

• onionshare_${VERSION}_amd64.snap
• OnionShare-$VERSION.msi
• OnionShare.dmg (rename it to OnionShare-$VERSION.dmg)
• onionshare-$VERSION.tar.gz

Create a PGP signature for each of these files, e.g:

gpg -a --detach-sign OnionShare-$VERSION.tar.gz
gpg -a --detach-sign [... and so on]

Create a release on GitHub:

• Match it to the version tag, put the changelog in description of the release
• Upload all 8 files (binary and source packages and their .asc signatures)

Update onionshare-cli on PyPi

cd cli
poetry install
poetry publish --build

Update Flathub

After there's a new release tag, make the Flathub package work here: https://github.com/flathub/org.onionshare.OnionShare

You must have flatpak and flatpak-builder installed, with flathub remote added (flatpak remote-add --if-not-exists --user flathub https://flathub.org/repo/flathub.flatpakrepo).

• Change the tag (for both onionshare and onionshare-cli) to match the new git tag
• Update tor, libevent, and obfs4 dependencies, if necessary
• Built the latest python dependencies using this tool (see below)
• Test the Flatpak package, ensure it works

# you may need to install toml
pip3 install --user toml

# clone flatpak-build-tools
git clone https://github.com/flatpak/flatpak-builder-tools.git

# get onionshare-cli dependencies
cd poetry
./flatpak-poetry-generator.py ../../onionshare/cli/poetry.lock
cd ..

# get onionshare dependencies
cd pip
./flatpak-pip-generator $(python3 -c 'import toml; print("\n".join(toml.loads(open("../../onionshare/desktop/pyproject.toml").read())["tool"]["briefcase"]["app"]["onionshare"]["requires"]))' |grep -v "./onionshare_cli" |grep -v -i "pyside2" |tr "\n" " ")
mv python3-modules.json onionshare.json

# use something like https://www.json2yaml.com/ to convert to yaml and update the manifest
# add all of the modules in both onionshare-cli and onionshare to the submodules of "onionshare"
# - poetry/generated-poetry-sources.json (onionshare-cli)
# - pip/python3-modules.json (onionshare)

Build and test the Flatpak package before publishing:

flatpak-builder build --force-clean --install-deps-from=flathub --install --user org.onionshare.OnionShare.yaml
flatpak run org.onionshare.OnionShare

Create a single-file bundle:

flatpak build-bundle ~/.local/share/flatpak/repo OnionShare-$VERSION.flatpak org.onionshare.OnionShare --runtime-repo=https://flathub.org/repo/flathub.flatpakrepo

Create a PGP signature for the flatpak single-file bundle:

gpg -a --detach-sign OnionShare-$VERSION.flatpak

Upload this .flatpak and its sig to the GitHub release as well.

Update Homebrew

• Make a PR to homebrew-cask to update the macOS version

Update onionshare.org

• Upload all 10 files to https://onionshare.org/dist/$VERSION/
• 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/

Update docs.onionshare.org

• Upload everything from docs/build/docs to https://docs.onionshare.org/

Update the community

• Upload all 10 files to the OnionShare team Keybase filesystem
• Email the onionshare-dev mailing list announcing the release
• Blog, tweet, toot, etc.