Difference between revisions of "ReleasingWesnoth"

From The Battle for Wesnoth Wiki
(→‎Tagging and extra release related steps: added git tagging to release commands)
(Link to new page so there is a chance to find it.)
 
(35 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 +
== This page is not maintained anymore. See [[Release_Steps]]. ==
 +
 +
== todo steps to add ==
 +
 +
Mac package: details in projectfiles/Xcode/README.md
 +
 +
Windows package: ?
 +
 +
Android package: (third party, but still, details?)
 +
 +
iOS package: ?
 +
 +
For us:
 +
 +
* forum post in News
 +
* forum post in Announcements
 +
* Updating the download page on the wiki
 +
* Updating the front page
 +
* rebuild the front page (<code>git pull</code> and <code>make</code> after SSHing to www.wesnoth.org)
 +
* Announcing the release on Discord
 +
* Announcing the release on Steam.
 +
** This included making a new header graphic if it's a stable release.
 +
* Announcing the release on Twitter with a link to the forum post
 +
 +
== Version numbering ==
 +
 +
We use the even/odd minor number convention.  A.B.C where B is even means stable and B is odd means unstable/development version.
 +
 +
1.15.x are development versions for 1.16.0.
 +
 +
A development version should be called "beta 1" when no further API changes are expected, nor string changes. At that point, translators and add-on authors can start working on 1.15.x without worrying that the rug be swept under their feet.
 +
 +
A development version should be called "release candidate 1" when all blockers have been fixed.
 +
 +
During the beta/RC/stable stages, no API changes (e.g., Lua/WML interfaces or semantics) should be made , nor large-scale or destabilizing internal changes, nor build dependencies changed. That's true from "1.15.x (1.16 beta 1)" and for the rest of the 1.16.x releases too. Such changes should be made in 1.17.x for 1.18.
 +
 
== Tools ==
 
== Tools ==
  
Line 17: Line 53:
 
Not strictly release associated though the pot-update part should be done right before every release.
 
Not strictly release associated though the pot-update part should be done right before every release.
  
−
* Run <code>utils/wesnoth-optipng</code> from the main directory of the checkout every now and then, requires the packages optipng, imagemagick and advancecomp
+
* Run <code>utils/wesnoth-optipng</code> from the main directory of the checkout every now and then (read: <b>very</b> rarely, because it enlarges the Git repository for <i>very</i> negligible reductions in distribution size), requires the packages optipng, imagemagick and advancecomp
−
* Run a <code>pot-update</code> regulary, once shortly before the release, this includes the following steps as of current 1.11.2 time:
+
* Run a <code>pot-update</code> regularly, once shortly before the release and before each string-freeze (including string-freezes in preparation for stable releases). This involves the following steps as of 1.13.3:
  
−
Change into the repository directory, pull (and rebase!)
+
  # target "pot-update" regenerates pot files and updates po files according to them
−
  # create build folder and cd into it
+
  # target "update-po4a" reruns po4a for man pages and manual
−
mkdir wesnoth-build && cd wesnoth-build
+
  # target "manual" regenerates manual
−
# run cmake and at leastenable the pot-update target
+
  scons pot-update update-po4a manual
−
cmake ../ -DENABLE_POT_UPDATE_TARGET=TRUE
 
−
 
−
  # Recreate the manpages (watch out for errors, they are very frequent!)
 
−
make update-po4a-man
 
−
  # Recreate the manual
 
−
make update-po4a-manual
 
−
  # Update all the other pot and po files
 
−
make pot-update
 
−
# make sure all files compile
 
−
make mo-update
 
 
   
 
   
−
# get out of the build folder back to the git folder
 
−
cd ../
 
 
  # Make sure that no new files were created in doc/, if new manpages/manuals were created, add them
 
  # Make sure that no new files were created in doc/, if new manpages/manuals were created, add them
 
  git status doc/
 
  git status doc/
 
   
 
   
 
  # Commit the bunch of updated po files and manpages/manuals
 
  # Commit the bunch of updated po files and manpages/manuals
−
  git add doc/ po/
+
  git commit doc/ po/
  
 
(the following commands should be run but are usually forgotten...)
 
(the following commands should be run but are usually forgotten...)
−
* Run <code>make</code> inside <code>data/tools</code> (runs a check for unresolved references, followed by <code>wmllint</code> with appropriate options, followed by a check for unused image and resource files)
+
* Run <code>make lint</code> inside <code>data/tools</code> (runs <code>wmllint</code> with appropriate options), fix warnings or prod campaign and content maintainers as needed
−
* Run <code>wmlindent</code> from <code>data/tools</code> to indent all content correctly
+
* Run <code>make reindent</code> from <code>data/tools</code> to reindent all mainline WML according to our conventions (probably don't want to do this too often as it may inconvenience coders)
 
* Have a look at the pages from the category [[:Category:Review_on_Release|Review on Release]]
 
* Have a look at the pages from the category [[:Category:Review_on_Release|Review on Release]]
 +
* If it's a 1.foo.0 release, start a new campaignd instance on add-ons.wesnoth.org and update the port numbers as in https://github.com/wesnoth/wesnoth/commit/211f14176ce57509003ca4542d388c526157093c
 +
* Announce to developers the string freeze start date (deadline for string changes) and the release cutoff date (deadline for commits)
 +
 +
== Release tasks ==
  
−
== Creating the tarball, xdelta and checksum ==
+
=== Preparation steps ===
−
First step of releasing is that you warn the devs via IRC and update the topic accordingly. Afterwards you just do the last steps and create the tarball:
+
* Merge the fixes on [[SpellingMistakes]]
−
* Make sure to run a pot-update (c.f. above)
+
* Review issues in the relevant labels (probably these? [https://github.com/wesnoth/wesnoth/labels/Blocker Blocker], [https://github.com/wesnoth/wesnoth/labels/Regression Regression], [https://github.com/wesnoth/wesnoth/labels/Urgent Urgent], and either [https://github.com/wesnoth/wesnoth/labels/Fwdport Fwdport] or [https://github.com/wesnoth/wesnoth/labels/Backport Backport] depending on what branch you're releasing) and milestones (for example, [https://github.com/wesnoth/wesnoth/milestone/9 1.15.2] and [https://github.com/wesnoth/wesnoth/milestone/13 1.16.0], if a development release; just [https://github.com/wesnoth/wesnoth/milestone/17 1.14.9], if a stable release).
−
* Bump the version in <code>src/wesconfig.h</code>
+
** For 1.15.3, review the [https://github.com/wesnoth/wesnoth/milestone/20 pre-1.16.0 string freeze] issues
−
* Check <code>changelog</code> and <code>players_changelog</code>, change the version of both
+
* Review the list of issues for the ''previous'' patch release (1.15.1 or 1.14.8), make sure it's empty.
−
* Commit
+
* Make sure to run and commit a pot-update (see above), and update to the latest revision of the branch if needed. At this point you should warn people to stop pushing commits to the branch you'll be using for the release so as to avoid last-minute work sync issues or new unexpected bugs.
−
* Do the following steps to generate the release files:
+
* Check <code>changelog</code> and <code>players_changelog</code> for completeness and correctness, line wrap to 80 columns.
 +
* Bump the version numbers in <code>src/wesconfig.h</code>, <code>Doxyfile</code>, <code>changelog</code>, <code>players_changelog</code>, and <code>projectfiles/Xcode/Info.plist</code> and commit. Note that as of version 1.13.2 there are additional <code>RC_VERSION_*</code> macros in <code>src/wesconfig.h</code> needed by Windows builds. Since unlike <code>VERSION</code> these aren't freeform values, they should represent the next release version whenever <code>VERSION</code> represents an in-dev version (e.g. if <code>VERSION</code> is <code>1.13.2+dev</code>, the <code>RC_VERSION_*</code> macros should have the values for <code>1.13.3</code> instead).
  
−
  # Update the git checkout, just to be sure that you have the latest version,
+
=== Generating the files ===
 +
 
 +
  # Update the git checkout, just to be sure that you have the
 +
# latest version
 +
 
  git pull --rebase
 
  git pull --rebase
 
   
 
   
−
  # export the git checkout into a release directory
+
  # Export the git checkout into a release tar archive (substitute
−
  git checkout-index -a -f --prefix=/absolute/path/to/export/root-folder/wesnoth-TAGNUMBER/
+
# $VERSION with the release version number and $BRANCH with the
 +
  # source branch). This will automatically exclude unwanted
 +
# directories from the archive following export-ignore rules in
 +
# .gitattributes
 
   
 
   
−
  # create the tarball
+
  git archive --format=tar --prefix="wesnoth-$VERSION/" $BRANCH > "wesnoth-$VERSION.tar"
−
cd /absolute/path/to/export/root-folder/
 
−
tar cf wesnoth-TAGNUMBER.tar wesnoth-TAGNUMBER
 
 
   
 
   
−
  # create the xdelta (assumption: the uncompressed aaa (oldversion) exists)
+
  # Create the xdelta patch for the archives (this assumes that the
−
  xdelta delta wesnoth-aaa.tar wesnoth-bbb.tar wesnoth-aaa.tar-wesnoth-bbb.tar.xdelta
+
  # uncompressed $OLDVERSION tar archive is present!)
 
   
 
   
−
  # compress the tarball
+
  xdelta delta wesnoth-$OLDVERSION.tar wesnoth-$VERSION.tar wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta
−
bzip2 -9 wesnoth-TAGNUMBER.tar
 
 
   
 
   
−
  # create md5sum
+
  # Compress the tarball
−
  md5sum wesnoth-TAGNUMBER.tar.bz2 > wesnoth-TAGNUMBER.tar.bz2.md5
+
   
 +
bzip2 wesnoth-$VERSION.tar
 +
 +
# Create the SHA256 sum for the tarball
 +
 +
sha256sum wesnoth-$VERSION.tar.bz2 > wesnoth-$VERSION.tar.bz2.sha256
  
 
== File upload ==
 
== File upload ==
 +
 
The following files should be ready for upload now:
 
The following files should be ready for upload now:
−
* wesnoth-TAGNUMBER.tar.bz2
 
−
* wesnoth-TAGNUMBER.tar.bz2.md5
 
−
* wesnoth-aaa.tar-wesnoth-bbb.tar.xdelta
 
  
−
These files now need to be uploaded to files.wesnoth.org (as backup) and to sourceforge.net. Just use rsync via ssh to do so. The exact paths for wesnoth.org might change when the server setup changes. After upload to wesnoth.org it might be faster to just ssh there and upload to sf.net from wesnoth.org.
+
* <code>wesnoth-$VERSION.tar.bz2</code>
 +
* <code>wesnoth-$VERSION.tar.bz2.sha256</code>
 +
* <code>wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta</code>
  
−
Upload to wesnoth:
+
You must upload these files to SourceForge.net and to <code>files.wesnoth.org/releases/</code> (as backup). Since the tarballs are very large it's recommended to use rsync via SSH instead of web uploads to guarantee their integrity. After uploading to wesnoth.org it might save time to rsync to SF.net from there.
−
rsync -avP -e ssh FILES ivanovic@wesnoth.org:WWW/html/files/
 
  
−
Upload to sf.net:
+
For uploading to wesnoth.org, you will need to ask the site administrators for help with setting up your SSH configuration, as well as determining the destination path for the files.
−
* STREAM: replace with ''wesnoth'' for dev releases and ''wesnoth-1.10'' for a stable release of the 1.10 series (change the version number accordingly)
 
−
* RELEASENAME: replace with the release name, e.g. ''wesnoth-1.11.2''
 
−
* Use your normal sf.net username and password for upload
 
  
−
  rsync -avP -e ssh FILES ivanovic,wesnoth@frs.sourceforge.net:/home/frs/project/w/we/wesnoth/STREAM/RELEASENAME
+
# Upload to files.wesnoth.org (path for reference purposes only,
 +
# does not reflect actual server set-up).
 +
 +
rsync -avP -e ssh <FILES> <USERNAME>@wesnoth.org:WWW/html/files/
 +
 +
# Upload to SF.net:
 +
#
 +
# * STREAM: replace with 'wesnoth' for development releases and
 +
#  'wesnoth-X.Y' for a stable release of the X.Y series.
 +
# * RELEASENAME: replace with the release name, e.g.
 +
#  'wesnoth-X.Y.Z'.
 +
 +
  rsync -avP -e ssh <FILES> <USERNAME>,wesnoth@frs.sourceforge.net:/home/frs/project/w/we/wesnoth/<STREAM>/<RELEASENAME>
  
 
== Build the release for testing ==
 
== Build the release for testing ==
−
The upload can already be started while the upload is running. The upload of the files might take a long time, so starting it early can be a good option. Before installing make sure that no old leftover files are there. Also remove the old preferences. Thi probably requires running as root for the installed files, user privilegies are enough to remove stuff in <code>~/.wesnoth-test</code>.
 
  
−
You can just reuse the export folder for building:
+
You can build the release for testing while the upload is in progress. Before installing the test build make sure that no old leftover files are there, and also remove the old preferences or (preferably) use the <code>utils/wesnoth-defaults</code> script found in the repository to use a throwaway preferences dir.
−
# cd into export folder
 
−
cd /absolute/path/to/export/root-folder/wesnoth-TAGNUMBER/
 
−
# create build folder
 
−
mkdir wesnoth-build && cd wesnoth-build
 
  
−
  # cmake command to create a test build with suffix -test
+
  # Depending on whether you already compressed the tarball or not
−
  cmake . -DBINDIR=/games-bin -DDATAROOTDIR=/games -DENABLE_SERVER=TRUE -DENABLE_CAMPAIGN_SERVER=TRUE \
+
tar -xvf wesnoth-$VERSION.tar
−
  -DPREFERENCES_DIR=.wesnoth-test -DBINARY_SUFFIX=-test -DDATADIRNAME=wesnoth-test \
+
tar -xvf wesnoth-$VERSION.tar.bz2
−
  -DENABLE_NOTIFICATIONS=TRUE
+
 +
cd wesnoth-$VERSION && mkdir build && cd build
 +
 +
# CMake command to create a test build with suffix -X.Y.Z to be
 +
# installed to /opt/wesnoth-X.Y.Z instead of /usr/local
 +
  cmake .. \
 +
-DCMAKE_INSTALL_PREFIX=/opt/wesnoth-X.Y.Z \
 +
-DENABLE_SERVER=TRUE \
 +
-DENABLE_CAMPAIGN_SERVER=TRUE \
 +
-DPREFERENCES_DIR=.wesnoth-X.Y.Z \
 +
-DBINARY_SUFFIX=-X.Y.Z \
 +
-DENABLE_NOTIFICATIONS=TRUE \
 +
-DENABLE_STRICT_COMPILATION=TRUE
 
   
 
   
−
  # build
+
  # Build
−
  LC_ALL=C nice -n 11 make
+
  make -j<N>
 
   
 
   
 
  # install
 
  # install
−
  su -c "make install"
+
  sudo make install
  
−
Now cd somewhere else and test ''wesnoth-test''. Running right from the sources is '''not''' enough to be sure that everything works as expected.
+
Now cd somewhere else and run the installed copy of the game (e.g. <code>/opt/wesnoth-X.Y.Z/bin/wesnoth</code>). Running right from the sources is '''not''' enough to be sure that everything works as expected.
  
 
== Test the build ==
 
== Test the build ==
Line 129: Line 182:
  
 
== Tagging and extra release related steps ==
 
== Tagging and extra release related steps ==
−
If everything does work, tag your release. Just use TAGNUMMER for the tag, no need to add wesnoth- in front.
 
−
git tag TAGNUMBER COMMITID_TO_TAG -m "tagged TAGNUMER, using commit COMMITID_TO_TAG"
 
−
git push --tags
 
  
−
Create an updated [http://www.wesnoth.org/macro-reference.html macro-reference.html] and upload it:
+
If everything works as expected, tag your release. Just use the version number (e.g. <code>1.13.2</code> or <code>1.14.0</code>) for the tag, no need to add <code>wesnoth-</code> in front:
−
  cd /absolute/path/to/export/root-folder/wesnoth-TAGNUMBER/data/tools
+
 
 +
git tag -a -m "Wesnoth $VERSION" $VERSION HEAD && git push $VERSION
 +
 
 +
Update [http://www.wesnoth.org/macro-reference.html macro-reference.html]:
 +
 
 +
  cd data/tools/
 
  make macro-reference.html
 
  make macro-reference.html
 
  scp macro-reference.html wesnoth@wesnoth.org:WWW/html/macro-reference.html
 
  scp macro-reference.html wesnoth@wesnoth.org:WWW/html/macro-reference.html
  
−
Create latest credits and use them to update the website
+
Regenerate the game credits and paste the contents to [[Credits]] on the wiki:
−
cd /absolute/path/to/export/root-folder/wesnoth-TAGNUMBER/
+
 
−
  data/tools/about_cfg_to_wiki -w /games-bin/wesnoth-test > about.wiki
+
  data/tools/about_cfg_to_wiki -w <PATH TO GAME EXECUTABLE> > about.wiki
 +
 
 +
== Alternative post-tag package creation method ==
 +
 
 +
This method requires tagging release before generating tarballs and doing uploads. It involves running a single script but this script needs to be modified each time to update versions. It also requires existing tarball of previous release against which to create xdelta.
  
−
Open about.wiki in a text editor and paste the content to [[Credits]].
+
  #!/bin/sh -xe
 +
  VERSION=1.15.2
 +
  OLDVERSION=1.15.1
 +
  git checkout $VERSION
 +
  git archive --format=tar --prefix="wesnoth-$VERSION/" $VERSION > "wesnoth-$VERSION.tar"
 +
  bunzip2 wesnoth-$OLDVERSION.tar.bz2
 +
  xdelta delta wesnoth-$OLDVERSION.tar wesnoth-$VERSION.tar wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta || true
 +
  bzip2 wesnoth-$VERSION.tar
 +
  sha256sum wesnoth-$VERSION.tar.bz2 > wesnoth-$VERSION.tar.bz2.sha256
 +
  scp -P 10222 wesnoth-$VERSION.tar.bz2 wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta loonycyborg@wesnoth.org:/srv/www/html/files/
 +
  scp -P 10222 wesnoth-$VERSION.tar.bz2.sha256 YOUR_WESNOTH_ORG_USERNAME@wesnoth.org:/srv/www/html/files/releases/
 +
  rsync -avP -e ssh wesnoth-$VERSION.tar.bz2 wesnoth-$VERSION.tar.bz2.sha256 wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta YOUR_SF_USERNAME,wesnoth@frs.sourceforge.net:/home/frs/project/w/we/wesnoth/wesnoth/wesnoth-$VERSION/
  
 
== Notify packagers ==
 
== Notify packagers ==
−
Once all steps above are done and the upload to sourceforge is finished, you still need to notify the packagers. The announcement should include the important changes for packagagers (especially path and requirementchanges) as well as the md5 of the tarball attached, Make sure to sign md5 and mail when sending.
 
  
−
This is the current list of packagers who want to be notified as of 1.11.2:
+
Once all steps above are done and the upload to sourceforge is finished, you still need to notify the packagers. The announcement should include the important changes for packagers (especially path, dependencies, and other build-time changes), as well as the SHA256 checksum of the tarball attached.
−
markus.schmeing  |ATTT| udo.edu (unofficial gentoo packages, basically inactive)
 
−
hhetter  |ATTT| novell.com (OpenSuse packager)
 
−
enqlave  |ATTT| gmail.com (unknown)
 
−
michael  |ATTT| sterretts.net (unknown)
 
−
sobotkap  |ATTT| centrum.cz (OpenSolaris)
 
−
rhonda  |ATTT| deb.at (current debian packager)
 
−
cycholka  |ATTT| wp.pl (old Windows packager)
 
−
amirserdang  |ATTT| gmail.com (old Mac OSX packager)
 
−
ben  |ATTT| happyspork.com (old Mac OSX packager)
 
−
wtogami  |ATTT| gmail.com (unknown)
 
−
alarantalara  |ATTT| gmail.com (current Mac OSX packager)
 
−
dougmencken  |ATTT| gmail.com (unknown)
 
−
lipka.boldizsar  |ATTT| gmail.com (unknown)
 
  
−
Basic text for such an announcement:
+
For the current list of packagers, check <code>/scratch/packagers-list</code> on the files.wesnoth.org filesystem.
−
  subject: Wesnoth TAGNUMBER is out!
+
 
−
  mailtext:
+
'''NOTE:''' Make sure that our "tier 1" packagers (currently Windows and OS X) whose content is hosted by us on SF.net upload the SHA256 sums of their files to files.wesnoth.org/releases/ as well!
−
  Hi,
+
 
−
  Wesnoth TAGNUMBER is out! :)
+
'''TODO:''' Upload not just the sha256 files but also the actual files, as a backup in case sf.net is down etc
−
  The sources are already available via sf.net and files.wesnoth.org (just as
+
 
−
backup). I will announce the release once the MacOSX and Windows binaries are
+
=== Example messages ===
−
done and uploaded. The announcement will not happen in the next 24h and if the
+
 
−
  MacOSX and Windows binaries take "too much time" I will just announce in 72
+
==== Development version ====
−
hours. In the meantime you can create and upload your packages.
+
  Subject: Wesnoth X.Y.Z is out!
 +
   
 +
  Hello,
 +
   
 +
  Wesnoth X.Y.Z, a new feature release in the X.Y.x development series, is out
 +
  now.
 
   
 
   
−
  Some foo about changes/additions/stuff to keep in mind, especially stuff from
+
  The sources are already available on SourceForge.net, and files.wesnoth.org
−
  the RELEASE_NOTES.
+
(for backup or in case you don't trust the authenticity of the files on
 +
  SF.net). We will announce the release within the next 72 hours. In the
 +
meantime you can create and upload your packages.
 
   
 
   
−
  Best regards and thank you for your contribution to Wesnoth
+
  Nothing has changed for packagers in terms of dependencies or install
−
  SIGNATURE
+
  locations in this release.
 
   
 
   
−
  attachment: wesnoth-TAGNUMBER.tar.bz2.md5
+
  Thank you for your contribution to Wesnoth!
  
−
Contact Soliton/Shadowmaster so that he updates the server to support the new version (required for development releases, should not be needed for stable releases after RC time is started)
+
==== Stable version ====
 +
Subject: Wesnoth X.Y.Z is out!
 +
 +
Hello,
 +
 +
Wesnoth X.Y.Z, a new maintenance release in the X.Y.x stable series, is out
 +
now.
 +
 +
The sources are already available on SourceForge.net, and files.wesnoth.org
 +
(for backup or in case you don't trust the authenticity of the files on
 +
SF.net). We will announce the release within the next 72 hours. In the
 +
meantime you can create and upload your packages.
 +
 +
As this is a stable maintenance release, nothing has changed for packagers in
 +
terms of dependencies or install locations.
 +
 +
Thank you for your contribution to Wesnoth!
  
 
== Cleanup and post release steps ==
 
== Cleanup and post release steps ==
−
Bump version in <code>wesnoth-VERSION+dev</code> in <code>src/wesconfig.h</code>, <code>changelog</code> and <code>players_changelog</code> and commit the change.
 
  
−
Remove the release related files (export folder, tarball, xdelta, ...).
+
Bump the version numbers in the files mentioned above in the release preparation steps and commit your changes. Consider deleting the test build, tarball, xdelta, etc. from your filesystem as needed.
 +
 
 +
Contact shadowm or Soliton to update the MP servers' configuration to allow users of the new release or rebuild the servers as needed (only required for development releases).
 +
 
 +
== The real announcement ==
  
−
== The real annoucement ==
+
Prepare the real announcement forum post for the day it is to be posted. To do so copy the last announcement from the release thread into the hidden forum (edit, then copy & paste). Edit the new copy to match the new release as needed, and leave it there for fixes and comments until the time for the real announcement comes. Make sure to use the items from <code>RELEASE_NOTES</code> (which you will purge after the final announcement is published).
−
Prepare the real announcement forum post for the day it is to be posted. To do so copy the last announcement from the release thread into the moderators forum (edit, then copy&paste). Adjust it to match the new release. And leave it there for fixes and comments until the time for the real announcement comes. Make sure to use the stuff from the RELEASE_NOTES and clean them afterwards.
 
  
−
Wait until the conditions from the mail to the packagers are met (waited at least 24h and OSX and Windows binary are ready OR 72h passed).
+
You should also prepare the front page/News forum post in advance.
  
−
Now do the following steps to get the real release out:
+
Wait until the announcement conditions are met (waited at least 24 hours and OS X and Windows builds are ready OR 72 hours passed).
−
* Update the downloads website in the wiki.
 
−
* Copy the prepared announcement forum post into the announcement category and post it as 'announcement'.
 
−
* Set the previous announcement to a 'normal' post.
 
−
* Update the frontpage:
 
−
** Change version in header to list the latest version.
 
−
** Update the news list and make sure to point to the correct forum post.
 
−
** If the news section is getting too long, remove some of the oldest posts.
 
−
* Copy the new news to [[Older_News]]
 
−
* Submit versions updates for stable versions to all sites that are known to monitor Wesnoth, ask the respective packagers to do so for OS specific sites (like apple.com).
 
  
−
== Sites monitoring Wesnoth releases ==
+
When ready to make the announcement public, do the following:
−
This is a (probably completely outdated) list of sites that monitor Wesnoth releases. Most of these require manual submissions of update request. This should be done by whoever has an account at the respective sites:
 
  
−
* http://freshmeat.net/projects/wesnoth
+
* Update [[Download]] in the wiki (currently takes the relevant contents from [[Template:StableDownload]] and [[Template:DevDownload]]).
−
* http://happypenguin.org/show?Battle%20for%20Wesnoth
+
* Post the contents of the new announcement post to the Release forum section as a new 'Announcement' topic.
−
* http://libsdl.org
+
* Set the previous announcement to a 'Normal' topic and lock it.
−
* http://linuxgames.com
+
* Post the new News forum post to the News forum section.
−
* http://icewalkers.com
+
* Update the wesnoth.org front page (yes, this has to be done by hand, I know, it sucks ― shadowm):
−
* http://tucows.com
+
** Change versions, sizes, and links in the overview section to point to the latest version.
−
* http://maccentral.com
+
** Update the front page news section with an HTML version of the News forum post.
−
* http://www.versiontracker.com
+
** If the front page news section is getting too large, remove some of the oldest posts.
−
* http://www.macgamefiles.com
+
* Copy the new news to [[Older_News]].
−
* http://www.apple.com
+
* Update topics on IRC and post to social media (Twitter, etc.) as applicable.
 +
* Clean up <code>RELEASE_NOTES</code> in the repository so it only contains the template for the next release.
  
 
[[Category:Development]]
 
[[Category:Development]]

Latest revision as of 13:51, 27 July 2024

This page is not maintained anymore. See Release_Steps.

todo steps to add

Mac package: details in projectfiles/Xcode/README.md

Windows package: ?

Android package: (third party, but still, details?)

iOS package: ?

For us:

  • forum post in News
  • forum post in Announcements
  • Updating the download page on the wiki
  • Updating the front page
  • rebuild the front page (git pull and make after SSHing to www.wesnoth.org)
  • Announcing the release on Discord
  • Announcing the release on Steam.
    • This included making a new header graphic if it's a stable release.
  • Announcing the release on Twitter with a link to the forum post

Version numbering

We use the even/odd minor number convention. A.B.C where B is even means stable and B is odd means unstable/development version.

1.15.x are development versions for 1.16.0.

A development version should be called "beta 1" when no further API changes are expected, nor string changes. At that point, translators and add-on authors can start working on 1.15.x without worrying that the rug be swept under their feet.

A development version should be called "release candidate 1" when all blockers have been fixed.

During the beta/RC/stable stages, no API changes (e.g., Lua/WML interfaces or semantics) should be made , nor large-scale or destabilizing internal changes, nor build dependencies changed. That's true from "1.15.x (1.16 beta 1)" and for the rest of the 1.16.x releases too. Such changes should be made in 1.17.x for 1.18.

Tools

Tools needed for releasing:

  • Normal tools to build everything from Wesnoth and to fetch the repository head (cmake based assumed for this page!)
  • po4a (to be able to update the manpages and manual)
  • docbook-xml-dtd (to generate the manual HTML files)
  • xdelta 1.x (to create the Xdelta files)
  • rsync for upload of tarballs

Tools for other processes:

  • optipng (only for needed to run utils/wesnoth-optipng, not for normal releases)
  • imagemagick (tool convert, only for needed to run utils/wesnoth-optipng, not for normal releases)
  • advancecomp (tool advdef, only for needed to run utils/wesnoth-optipng, not for normal releases)

General maintenance

Not strictly release associated though the pot-update part should be done right before every release.

  • Run utils/wesnoth-optipng from the main directory of the checkout every now and then (read: very rarely, because it enlarges the Git repository for very negligible reductions in distribution size), requires the packages optipng, imagemagick and advancecomp
  • Run a pot-update regularly, once shortly before the release and before each string-freeze (including string-freezes in preparation for stable releases). This involves the following steps as of 1.13.3:
# target "pot-update" regenerates pot files and updates po files according to them
# target "update-po4a" reruns po4a for man pages and manual
# target "manual" regenerates manual
scons pot-update update-po4a manual

# Make sure that no new files were created in doc/, if new manpages/manuals were created, add them
git status doc/

# Commit the bunch of updated po files and manpages/manuals
git commit doc/ po/

(the following commands should be run but are usually forgotten...)

  • Run make lint inside data/tools (runs wmllint with appropriate options), fix warnings or prod campaign and content maintainers as needed
  • Run make reindent from data/tools to reindent all mainline WML according to our conventions (probably don't want to do this too often as it may inconvenience coders)
  • Have a look at the pages from the category Review on Release
  • If it's a 1.foo.0 release, start a new campaignd instance on add-ons.wesnoth.org and update the port numbers as in https://github.com/wesnoth/wesnoth/commit/211f14176ce57509003ca4542d388c526157093c
  • Announce to developers the string freeze start date (deadline for string changes) and the release cutoff date (deadline for commits)

Release tasks

Preparation steps

  • Merge the fixes on SpellingMistakes
  • Review issues in the relevant labels (probably these? Blocker, Regression, Urgent, and either Fwdport or Backport depending on what branch you're releasing) and milestones (for example, 1.15.2 and 1.16.0, if a development release; just 1.14.9, if a stable release).
  • Review the list of issues for the previous patch release (1.15.1 or 1.14.8), make sure it's empty.
  • Make sure to run and commit a pot-update (see above), and update to the latest revision of the branch if needed. At this point you should warn people to stop pushing commits to the branch you'll be using for the release so as to avoid last-minute work sync issues or new unexpected bugs.
  • Check changelog and players_changelog for completeness and correctness, line wrap to 80 columns.
  • Bump the version numbers in src/wesconfig.h, Doxyfile, changelog, players_changelog, and projectfiles/Xcode/Info.plist and commit. Note that as of version 1.13.2 there are additional RC_VERSION_* macros in src/wesconfig.h needed by Windows builds. Since unlike VERSION these aren't freeform values, they should represent the next release version whenever VERSION represents an in-dev version (e.g. if VERSION is 1.13.2+dev, the RC_VERSION_* macros should have the values for 1.13.3 instead).

Generating the files

# Update the git checkout, just to be sure that you have the
# latest version

git pull --rebase

# Export the git checkout into a release tar archive (substitute
# $VERSION with the release version number and $BRANCH with the
# source branch). This will automatically exclude unwanted
# directories from the archive following export-ignore rules in
# .gitattributes

git archive --format=tar --prefix="wesnoth-$VERSION/" $BRANCH > "wesnoth-$VERSION.tar"

# Create the xdelta patch for the archives (this assumes that the
# uncompressed $OLDVERSION tar archive is present!)

xdelta delta wesnoth-$OLDVERSION.tar wesnoth-$VERSION.tar wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta

# Compress the tarball

bzip2 wesnoth-$VERSION.tar

# Create the SHA256 sum for the tarball

sha256sum wesnoth-$VERSION.tar.bz2 > wesnoth-$VERSION.tar.bz2.sha256

File upload

The following files should be ready for upload now:

  • wesnoth-$VERSION.tar.bz2
  • wesnoth-$VERSION.tar.bz2.sha256
  • wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta

You must upload these files to SourceForge.net and to files.wesnoth.org/releases/ (as backup). Since the tarballs are very large it's recommended to use rsync via SSH instead of web uploads to guarantee their integrity. After uploading to wesnoth.org it might save time to rsync to SF.net from there.

For uploading to wesnoth.org, you will need to ask the site administrators for help with setting up your SSH configuration, as well as determining the destination path for the files. 

# Upload to files.wesnoth.org (path for reference purposes only,
# does not reflect actual server set-up).

rsync -avP -e ssh <FILES> <USERNAME>@wesnoth.org:WWW/html/files/

# Upload to SF.net:
#
# * STREAM: replace with 'wesnoth' for development releases and
#   'wesnoth-X.Y' for a stable release of the X.Y series.
# * RELEASENAME: replace with the release name, e.g.
#   'wesnoth-X.Y.Z'.

rsync -avP -e ssh <FILES> <USERNAME>,wesnoth@frs.sourceforge.net:/home/frs/project/w/we/wesnoth/<STREAM>/<RELEASENAME>

Build the release for testing

You can build the release for testing while the upload is in progress. Before installing the test build make sure that no old leftover files are there, and also remove the old preferences or (preferably) use the utils/wesnoth-defaults script found in the repository to use a throwaway preferences dir. 

# Depending on whether you already compressed the tarball or not
tar -xvf wesnoth-$VERSION.tar
tar -xvf wesnoth-$VERSION.tar.bz2

cd wesnoth-$VERSION && mkdir build && cd build

# CMake command to create a test build with suffix -X.Y.Z to be
# installed to /opt/wesnoth-X.Y.Z instead of /usr/local
cmake .. \
		-DCMAKE_INSTALL_PREFIX=/opt/wesnoth-X.Y.Z \
		-DENABLE_SERVER=TRUE \
		-DENABLE_CAMPAIGN_SERVER=TRUE \
		-DPREFERENCES_DIR=.wesnoth-X.Y.Z \
		-DBINARY_SUFFIX=-X.Y.Z \
		-DENABLE_NOTIFICATIONS=TRUE \
		-DENABLE_STRICT_COMPILATION=TRUE

# Build
make -j<N>

# install
sudo make install

Now cd somewhere else and run the installed copy of the game (e.g. /opt/wesnoth-X.Y.Z/bin/wesnoth). Running right from the sources is not enough to be sure that everything works as expected.

Test the build

This at least includes the following:

  • Start the editor, check if creating a map is possible
  • Start the game and try to connect to the official multiplayer server and to the add-on server
  • Start the server, connect to it using the game to see if you can enter the lobby
  • Check if in the game each campaign does start
  • Check if you can start the in-game help and the credits
  • Check if it is possible to create a local game
  • Play at least one game/scenario (or droid your side to let the AI play), this can either be a normal campaign scenario or a multiplayer game

If all of those points are working as expected, go on, if not, fix the problems and restart from the very beginning.

Tagging and extra release related steps

If everything works as expected, tag your release. Just use the version number (e.g. 1.13.2 or 1.14.0) for the tag, no need to add wesnoth- in front: 

git tag -a -m "Wesnoth $VERSION" $VERSION HEAD && git push $VERSION

Update macro-reference.html: 

cd data/tools/
make macro-reference.html
scp macro-reference.html wesnoth@wesnoth.org:WWW/html/macro-reference.html

Regenerate the game credits and paste the contents to Credits on the wiki: 

data/tools/about_cfg_to_wiki -w <PATH TO GAME EXECUTABLE> > about.wiki

Alternative post-tag package creation method

This method requires tagging release before generating tarballs and doing uploads. It involves running a single script but this script needs to be modified each time to update versions. It also requires existing tarball of previous release against which to create xdelta. 

 #!/bin/sh -xe
 VERSION=1.15.2
 OLDVERSION=1.15.1
 git checkout $VERSION
 git archive --format=tar --prefix="wesnoth-$VERSION/" $VERSION > "wesnoth-$VERSION.tar"
 bunzip2 wesnoth-$OLDVERSION.tar.bz2
 xdelta delta wesnoth-$OLDVERSION.tar wesnoth-$VERSION.tar wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta || true
 bzip2 wesnoth-$VERSION.tar
 sha256sum wesnoth-$VERSION.tar.bz2 > wesnoth-$VERSION.tar.bz2.sha256
 scp -P 10222 wesnoth-$VERSION.tar.bz2 wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta loonycyborg@wesnoth.org:/srv/www/html/files/
 scp -P 10222 wesnoth-$VERSION.tar.bz2.sha256 YOUR_WESNOTH_ORG_USERNAME@wesnoth.org:/srv/www/html/files/releases/
 rsync -avP -e ssh wesnoth-$VERSION.tar.bz2 wesnoth-$VERSION.tar.bz2.sha256 wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta YOUR_SF_USERNAME,wesnoth@frs.sourceforge.net:/home/frs/project/w/we/wesnoth/wesnoth/wesnoth-$VERSION/

Notify packagers

Once all steps above are done and the upload to sourceforge is finished, you still need to notify the packagers. The announcement should include the important changes for packagers (especially path, dependencies, and other build-time changes), as well as the SHA256 checksum of the tarball attached.

For the current list of packagers, check /scratch/packagers-list on the files.wesnoth.org filesystem.

NOTE: Make sure that our "tier 1" packagers (currently Windows and OS X) whose content is hosted by us on SF.net upload the SHA256 sums of their files to files.wesnoth.org/releases/ as well!

TODO: Upload not just the sha256 files but also the actual files, as a backup in case sf.net is down etc

Example messages

Development version

Subject: Wesnoth X.Y.Z is out!

Hello,

Wesnoth X.Y.Z, a new feature release in the X.Y.x development series, is out 
now.

The sources are already available on SourceForge.net, and files.wesnoth.org 
(for backup or in case you don't trust the authenticity of the files on 
SF.net). We will announce the release within the next 72 hours. In the 
meantime you can create and upload your packages.

Nothing has changed for packagers in terms of dependencies or install 
locations in this release.

Thank you for your contribution to Wesnoth!

Stable version

Subject: Wesnoth X.Y.Z is out!

Hello,

Wesnoth X.Y.Z, a new maintenance release in the X.Y.x stable series, is out 
now.

The sources are already available on SourceForge.net, and files.wesnoth.org 
(for backup or in case you don't trust the authenticity of the files on 
SF.net). We will announce the release within the next 72 hours. In the 
meantime you can create and upload your packages.

As this is a stable maintenance release, nothing has changed for packagers in
terms of dependencies or install locations.

Thank you for your contribution to Wesnoth!

Cleanup and post release steps

Bump the version numbers in the files mentioned above in the release preparation steps and commit your changes. Consider deleting the test build, tarball, xdelta, etc. from your filesystem as needed.

Contact shadowm or Soliton to update the MP servers' configuration to allow users of the new release or rebuild the servers as needed (only required for development releases).

The real announcement

Prepare the real announcement forum post for the day it is to be posted. To do so copy the last announcement from the release thread into the hidden forum (edit, then copy & paste). Edit the new copy to match the new release as needed, and leave it there for fixes and comments until the time for the real announcement comes. Make sure to use the items from RELEASE_NOTES (which you will purge after the final announcement is published).

You should also prepare the front page/News forum post in advance.

Wait until the announcement conditions are met (waited at least 24 hours and OS X and Windows builds are ready OR 72 hours passed).

When ready to make the announcement public, do the following:

  • Update Download in the wiki (currently takes the relevant contents from Template:StableDownload and Template:DevDownload).
  • Post the contents of the new announcement post to the Release forum section as a new 'Announcement' topic.
  • Set the previous announcement to a 'Normal' topic and lock it.
  • Post the new News forum post to the News forum section.
  • Update the wesnoth.org front page (yes, this has to be done by hand, I know, it sucks ― shadowm):
    • Change versions, sizes, and links in the overview section to point to the latest version.
    • Update the front page news section with an HTML version of the News forum post.
    • If the front page news section is getting too large, remove some of the oldest posts.
  • Copy the new news to Older_News.
  • Update topics on IRC and post to social media (Twitter, etc.) as applicable.
  • Clean up RELEASE_NOTES in the repository so it only contains the template for the next release.
Retrieved from "https://wiki.wesnoth.org/index.php?title=ReleasingWesnoth&oldid=73326"
This page was last edited on 27 July 2024, at 13:51.