Latest Posts

Changes in ReleasingWidelands

Editor Comment

Versioning info update


Revision Differences of Revision 64

## Releasing new versions of Widelands ¶

[TOC] ¶

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](https://github.com/widelands/widelands/issues/3979) 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](https://salsa.debian.org/games-team/widelands/) ¶
* check docs (everything in data/txts, debian, website wiki) ¶
* [[ TranslationMaintenance/ | 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. ¶
* [[ ReleasingWidelands/#maintenance | 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` ¶
* [[ ReleasingWidelands/#maintenance | 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: ¶
* [[ ReleasingWidelands/#maintenance | 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](https://git-scm.com/docs/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](https://git-scm.com/docs/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: ¶
* Discuss problems with this release. Update this checklist with good changes accordingly. ¶

* Encourage people to update infos about widelands on the web: [Wikipedia](https://en.wikipedia.org/wiki/Widelands), [Indie DB](https://www.indiedb.com/games/widelands) [LibreGameWiki](https://libregamewiki.org/Widelands), [Giant Bomb](http://www.giantbomb.com/widelands/3030-55521/), [Itch.io](https://widelands.itch.io/widelands) [Heise](https://www.heise.de/download/product/widelands-51404) [OMG! Ubuntu!](https://www.omgubuntu.co.uk/) and more. ¶

* 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](http://jrsoftware.org) -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 [[ BuildingWidelands/#building_with_cmake | 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](https://git-scm.com/docs/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](https://code.launchpad.net/~widelands-dev/+recipe/widelands-daily) includes al the latest Ubuntu versions.