Making Releases

• Bump the version number in tiled.qbs, appveyor.yml, docs/conf.py and org.mapeditor.Tiled.appdata.xml
• Update the NEWS.md and org.mapeditor.Tiled.appdata.xml files with the main changes since the last release

• Make sure copyright year in About Dialog is up-to-date
• Update the translation files (by running dist/update-translations.sh from the root folder)
• Announce the string freeze to the translators

The process of making a macOS release is entirely automated on GitHub Actions. It is triggered on every push, and automatically uploaded to a new release when a tag is pushed. The following steps are required for manual creation of an installer:

First, make sure you can compile Tiled. You can rely on brew for installing both qt and qbs, after which you do a one-time set up of Qbs:

qbs setup-toolchains --detect
qbs setup-qt /usr/local/opt/qt/bin/qmake qt-brew
qbs config profiles.qt-brew.baseProfile xcode-macosx-x86_64
qbs config defaultProfile qt-brew

Alternatively, you can install any other version of Qt. For Tiled releases I currently use Qt 5.15 LTS, which ensures that Tiled can run on macOS 10.13+.

Open the Terminal, and cd into the base folder of your Tiled checkout.

Run qbs to build Tiled:

qbs install --install-root install config:release

If it builds, you should have a Tiled.app in the install folder. You should run macdeployqt on it to copy the relevant Qt libs and plugins into it and apply the fixup-install-names.rb script to address remaining library loading issues. Then open it and make sure it works properly:

/usr/local/opt/qt/bin/macdeployqt install/Tiled.app
cd install
ruby ../dist/macos/fixup-install-names.rb
open Tiled.app

The following steps are automated as part of the GitHub Actions workflow as well.

codesign --deep --force --verify --verbose --sign "<your_developer_ID>" --options runtime Tiled.app

After signing, the Tiled.app is zipped up and submitted for notarization:

ditto -c -k --sequesterRsrc --keepParent Tiled.app Tiled-$TILED_VERSION-macos.zip
xcrun altool -type osx --notarize-app --primary-bundle-id "org.mapeditor.Tiled" --username "<developer_email>" --password "<app_password>" --file Tiled-$TILED_VERSION-macos.zip

If the notarization was successful, the app can be stapled:

xcrun stapler staple -v Tiled.app

Now we can zip up the app again for distribution!

The process of making a Windows release is entirely automated on AppVeyor. It is triggered when a tag is pushed. The following steps are required for manual creation of an installer:

• Install Qt. Releases can be made based on either MinGW 8.1 (32-bit or 64-bit) or Visual Studio 2013 (32-bit or 64-bit).
• Install the WiX toolset.
• Set either the TILED_SNAPSHOT or TILED_RELEASE environment variable to true.
• Build Tiled using Qbs (tiled.qbs), with the property projects.Tiled.windowsInstaller:true to enable building of the installer (when building from Qt Creator, put this in the Properties field in the Qbs build step).

If the build succeeds, you should find a tiled-...-winXX.msi file in the build directory.

Other packages to update:

• The Chocolatey package, at https://github.com/mapeditor/chocolatey-tiled
• The WinGet package (might be taken care of by an automated system already)

Tiled is being packaged by others for various distributions. In addition, we are releasing an AppImage on GitHub and itch.io, as well as maintaining a snap and a Flatpak package, which covers most Linux systems.

The Tiled AppImage is built on GitHub Actions and uploaded to GitHub releases. You can find the commands in .github/workflows/packages.yml file in the repository.

Remember to flag the Arch Linux package as Out-of-Date.

Tiled is available as a snap on https://snapcraft.io/tiled. A snap is built automatically for each new commit at https://snapcraft.io/tiled/builds and published to the "edge" channel. Tagged releases are built for 64-bit Linux on GitHub Actions and published to the "candidate" channel.

Once the release has been built, promote it to the appropriate channel on https://snapcraft.io/tiled/releases. Or on the command-line as follows:

snapcraft release tiled <revision> beta,candidate,stable

GitHub Actions builds the snap only for amd64 and arm64. The remaining architectures published to the store (currently s390x and ppc64el) are built with snapcraft remote-build, which runs the builds on Launchpad's build farm. Run this from the root of the Tiled checkout:

snapcraft login
snapcraft remote-build --launchpad-accept-public-upload --build-for s390x,ppc64el

• --launchpad-accept-public-upload is required, since remote builds are publicly visible on Launchpad.
• The architecture list comes from the platforms declaration in snap/snapcraft.yaml. qaseprite is skipped on s390x and ppc64el (it does not build there); armhf is currently blocked by Qt 5 on Ubuntu noble.
• If a remote build hangs or fails in a confusing way, removing ~/.cache/snapcraft (or just its remote-build subdirectory) and retrying usually clears it.

When the builds finish you get one .snap per architecture. Upload each to the store, then release the resulting revisions to the appropriate channels as above:

snapcraft upload tiled_<version>_<arch>.snap
snapcraft release tiled <revision> beta,candidate,stable

Update download link and sha256 at https://github.com/flathub/org.mapeditor.Tiled.

While snapshot builds are pushed to itch.io automatically, releases are done manually as follows:

mkdir windows-64bit
mkdir windows-32bit
mkdir winxp-32bit
mkdir linux-64bit

mv Tiled-$TILED_VERSION-win64.msi windows-64bit
mv Tiled-$TILED_VERSION-win32.msi windows-32bit
mv Tiled-$TILED_VERSION-winxp.msi winxp-32bit
mv Tiled-$TILED_VERSION-x86_64.AppImage linux-64bit

butler push --userversion=$TILED_VERSION windows-64bit thorbjorn/tiled:windows-64bit
butler push --userversion=$TILED_VERSION windows-32bit thorbjorn/tiled:windows-32bit
butler push --userversion=$TILED_VERSION winxp-32bit thorbjorn/tiled:winxp-32bit
butler push --userversion=$TILED_VERSION Tiled-$TILED_VERSION-macos.zip thorbjorn/tiled:macos
butler push --userversion=$TILED_VERSION linux-64bit thorbjorn/tiled:linux-64bit

Tiled checks https://www.mapeditor.org/versions.json for new versions. If the checked version is more recent that the installed version, a notification about the new version appears in the status bar.

The versions.json file can be edited on the gh-pages branch.