Latest Posts

ReleasingWidelands

Releasing new versions of Widelands

This document is about what steps are to perform to release a new build of Widelands.

We release one release candidate before each release, to make sure no completely stupid mistakes creep into a release. The steps for preparing the RC are mostly the same as the steps for preparing the final release, to ensure that problems with the release problems are found with the release candidate.

Versioning System

Stable versions are called X.Y where X is the major version and Y the minor version, e.g. 1.0. The PPA builds are always prefixed with 2: (this is the versioning epoch – never, ever change this constant!), e.g. 2:1.0.
For each release, the minor version is incremented by 1. Exception: If a release breaks compatibility to the previous release (which we try to avoid if somehow possible!), we instead increment the major version by 1 and reset the minor version to 0. When we do this, be sure to update the file NEXT_STABLE_VERSION and the daily PPA version.

The release candidates for version X.Y are called X.Y~rcZ (e.g. 1.0~rc1).

If the next stable release will be X.Y, development versions are called X.Y~git34567 (where 34567 is the git revision) or X.Y~bzr9876 (where 9876 is the bazaar revision); e.g. a version between 1.0 and 1.1 could be 1.1~git34567. The daily PPA builds are called 2:X.Y~bzr9876-202000000000 (where 2 is the epoch (do not change!), X.Y the next stable version, and 9876 the bazaar revision number; the long number at the end denotes the date and time of the build assigned by Launchpad).

In order to minimize confusion with versioning comparison rules, just keep in mind that a development version always begins with X.Y~ directly followed by a lowercase character that comes earlier in the alphabet than r, then optionally more characters, and then a running number.

If we have to backport fixes to version X.Y, the backported version will be X.Y.Z (e.g. the first backport to 1.0 is 1.0.1).

In GitHub tags, we prefix the version with v (e.g. v1.0 for version 1.0).
Note that the string in the lower-right corner of the Widelands main menu will look like 1.0~git24681[2efff03@master](Release) – the actual version is only the part 1.0~git24681! The [2efff03@master] is additional branch info and (Release) is the build configuration. Our detect_revision script returns the actual version plus the branch info part concatenated to a single string.

We switched to the described versioning scheme between the releases build-21 and 1.0. See here for a very detailed explanation.

Maintenance

  • update developers
  • update changelog
  • update copyright year by running utils/update_copyright.py <year>
    → additionally update the copyright year in utils/win32/innosetup/Widelands.iss, utils/win32/widelands.rc.cmake, data/txts/LICENSE.lua, and debian/copyright.
    (If you notice that this list is incomplete, please update it!)
  • Synchronize the debian directory with any changes from the Debian packaging repository
  • check docs (everything in data/txts, debian, website wiki)
  • update and validate translations . Double-check the hits from the printf-filter, because errors there can crash Widelands. We are getting some hits that are OK though, for example 5%% chance = 5%%-Chance in the German translation is OK.

Step 1: First-Snow Feature Freeze

  • Implement or reschedule targeted features for this build.
  • Maintenance
  • Agree on a date for first-snow feature freeze on widelands-public.
  • First-Snow feature freeze means:
    • no new features
    • no style fixes
    • no changes to campaigns
    • no new tagged strings
    • only minimal invasive bug fixes. That is if a bug can be fixed in a dirty-but-minimal-invasive change and in a correct way, the one that doesn't touch on any other code should be preferred and the correct way should go into a feature branch.
  • Announce the feature freeze date on the homepage to give translators/graphic artists a chance to catch up.
    • Prepare updated hand-made illustrations.
  • Announce a string freeze on Transifex.

Development should not cease but continue in feature branches. No more stuff should go to trunk though. As soon as all targeted bugs are fixed, we continue with

Step 2: Winter-Time feature freeze (The Real Feature freeze)

  • When all targeted bugs are fixed, a date for winter-time feature freeze is set. This should be roughly two weeks from the last bug's fixings date. One week after this the build candidate release is to be scheduled.
  • Run utils/optimize_pngs.py
  • Maintenance
  • Update the screenshots in debian/widelands.appdata.xml.stub.
  • Double-check copyright year in main menu and About tab.
  • This feature freeze extends to everything: from translatable strings to media, code, style. So there is one week where everything should already be perfectly working before the build candidate just to make sure that no last minute things come up. Translations can still be pulled though as long as the validator is run and double-checked (see maintenance stuff)
  • Obviously, new surfacing critical bugs are to be vanquished. Non critical bugs are to be deferred to the next version. What's critical should be discussed on the mailing list if there is no consensus.
  • The following things should be tested manually:
    • Replays with all win conditions
    • Click through all the encyclopedia screens
    • Multiplayer game
    • Tutorials
    • All Starting Conditions with all tribes (AI games will suffice)
    • Fiddle with the user interface and try to break stuff
  • Create a video trailer and put captions up for translation

Step 3: Build candidate

  • On the build candidate day the release does the following:

    • Maintenance
    • Branch from trunk and lift feature freeze. From now on, all bug fixes need to be cherry-picked between the release branch and trunk.
    • Add a proper WL_RELEASE file; update version information for AppVeyor (appveyor.yml), InnoSetup (utils/win32/innosetup/Widelands.iss), and in xdg/widelands.6 and utils/win32/widelands.rc.cmake.
    • Tag the release in the new branch
    • Mark all bugs that have Fix Committed as Fix Released. Add as comment the name of this build candidate.
    • Disable the milestone. Do not mark it as release yet.
    • Use git archive to export the source package (tar.bz2).
    • Upload the source tarball so that packagers can use it as reference.
    • Inform the packagers.
    • Add a new milestone for the final build

  • As soon as Windows, Mac and Linux binaries are available:

    • Mark the milestone as a release, upload the packages.
    • Add a post on the homepage.

Approximately one week after the release candidate, the final release should follow:

Step 4: Releasing

  • Fix a date for release on widelands public.
  • On the date:
    • Update the WL_RELEASE file and the version information for AppVeyor and InnoSetup.
    • Update the release information in debian/widelands.appdata.xml.stub, then run utils/update_appdata.py.
    • Copy the version changes in utils/win32/widelands.rc.cmake, xdg/widelands.6, and xdg/org.widelands.Widelands.appdata.xml* to the master branch as well. Update the file NEXT_STABLE_VERSION in master.
    • Mark all bugs that have Fix Committed as Fix Released. Add as comment the name of this build.
    • Tag the build in the build branch
    • Disable the milestone. Do not mark it as release yet.
    • Use git archive to export the source package (tar.bz2). Upload the source tarball so that packagers can use it as reference.
    • Upload the source package for packagers to find.
    • Inform the packagers.
    • Export the release branch to Launchpad, create a Recipe, and trigger a build for the stable PPA. Update the version string for the daily-PPA recipe as well.
  • As soon as Windows, Mac and Linux binaries are available:
    • Prepare a release statement for news etc.; use release statements of previous releases as a template.
    • Add translated captions to video trailer and publish
    • Mark the milestone as a release, upload the packages.
    • Update the DownloadPage to link to the new build.
    • Replace hand-made illustrations with the updated ones.
    • Update the screenshot section.
    • Send a Mail to widelands-announce with the release-statement
    • Announce on launchpad with the release-statement and full changelog
    • Add a post on the homepage.

Step 5: Post Release

  • Post-Release Mail to widelands-public:

  • Send cap-over-the-mill Mail to widelands-public about the next build

    • State organisatorial plans
    • State project driver vision plans
    • State plans as a developer
    • encourage other developers to post replies and their own plans.

Creating binary packages

Windows

For compilation of widelands-binary take a look at Buildingwidelandsunderwindowsnew and the README-file in [widelands-trunk]/build/win32

Compilation of a Setup-file is done via /build/win32/innosetup/Widelands.iss Script, which can be run with Inno Setup -Compiler.

Linux (directory independent)

These points are intended to help in creating a tarball that can easily be extracted and run in-place (e.g. in a user's home directory). For general Linux build info, see Build using cmake , among others.

Please note, that the locale directory must be correct; otherwise, Widelands will not find translations. Adding the parameters -DCMAKE_INSTALL_PREFIX="<prefix>" -DCMAKE_BINDIR="<gamesdir>" -DCMAKE_DATADIR="<datadirpath>" -DCMAKE_LOCALEDIR="<widelandslocaledir>" to the cmake command line should work, but be sure to test the binary package before the actual release.

These are the suggested steps for building the package:

  • Extract the release source package (using git archive).
  • Build the widelands executable using cmake and make (but be aware of the "locale" point above).
  • Perform some basic test (e.g. that translations are found).
  • Delete everything that is only relevant for source packages.
  • Create the tarball.
  • Extract the tarball into a new directory and perform some basic tests before uploading.

Ubuntu Dailies

Check regularly that our Launchpad recipe for widelands-daily includes al the latest Ubuntu versions.

Tagged with: Development, help