Wikia

Freeciv

Release

703pages on
this wiki
Talk0

Release process Edit

Freeciv is using subversion branches and tags in the release process. Development of new features take place on the trunk code. When a new feature set on trunk is deemed feature complete enough for general use, the trunk source tree will be branched into a "stable" branch, named with the pattern SX_Y where X_Y is the version number, ex. S2_2. When we're ready to make a public release from the branch, a tag is created with this naming: RX_Y_Z where R stands for "release", X_Y is taken from the branch, and Z is the minor version; ex. R2_2_0.

Before the release Edit

Translations and string freeze Edit

Announce the intention to make a release in plenty of time on freeciv-i18n. Decide on and announce a string freeze policy for the release. For a minor release, a week of frozen strings should usually be sufficient. Betas and release candidates do not require a string freeze.

Preliminary NEWS Edit

It's often a good idea to start preparing the NEWS file ahead of time, if possible. See the guidelines at #NEWS for details.

Making a release Edit

This is the quick checklist for making a release. This applies mostly to minor releases; major releases take a lot more work (some hints below).

PO filesEdit

Check for and commit any translations -- check for posts to freeciv-i18n, and to other upload locations listed in Translations.

Run "make update-po" in the po/ directory or, from 2.5, in each subdirectory under translations/. Usually it's best to commit the changes.

NEWSEdit

Make a diff from the previous release version. From this the news can be created. NEWS goes into a wiki page named something like NEWS-2.5.5. (If this has been started before the day of the release, make sure it's up to date.)

For the first release from a new major branch (likely a "beta1"), create a NEWS-x.y.0 page describing changes since the previous stable branch. This is a major undertaking. List only notable new features and major bugfixes since the previous major branch, not every single change. Don't include changes that are likely to appear in a future release from the previous branch. This file should be a reasonably accurate "what's new in 2.5.x compared to 2.4.y" for all x and y. (A copy of this will go into NEWS in the tarball.)

For all other (minor) releases, the NEWS-x.y.z page should usually account for every change, although minor fixes can often be grouped under headings like "memory leak fixes" or "help improvements". In the beta/RC cycle leading up to x.y.0, make sure NEWS-x.y.0 stays up to date as well. (A copy of this will go into NEWS-x.y in the tarball.)

DocsEdit

Make sure the NEWS and NEWS-x.y files in svn are up-to-date with the NEWS page(s) on wiki. A script which helps scrape and format NEWS from wiki is currently attached to GNAPATCH#3488.

Make sure the version number at the top of NEWS-x.y matches the coming release.

For a new major release x.y.0:

  • For beta1, make sure that the NEWS file has the right version at the top, and that it contains up-to-date news for previous major versions as well as this one.
  • For beta2, create the NEWS-x.y file in svn on the appropriate branch, and make sure it's listed in Makefile.am (GNAPATCH#3488 has examples), and ensure it's cross-referenced from NEWS. (This file does not exist on trunk, and will have nothing to say for beta1.)

Consider whether doc/FAQ needs refreshing from wiki (using doc/generate_FAQ.pl to scrape it).

Bump versionEdit

(Be sure you're going to complete the release the same day before committing this...)

Edit fc_version and bump the version number. Ensure that there's still a '+' (plus) to indicate non-release code. Commit this to the branch.

ChangeLogEdit

Updating the ChangeLog in svn can be done through the svn log command. Do something like svn log -v -r xxxxx:yyyyy where xxxxx is the last revision as of branching/tagging and yyyyy is the revision after the one at the top of the current changelog. Paste the output into the top of the ChangeLog file.

PeopleEdit

The People page can be updated from the new ChangeLog, as needed.

CommittingEdit

The ChangeLog should be the very last thing to be committed before the release, so that it includes info about all the other commits.

TaggingEdit

Copy the branch into a tag. Something like:

svn copy svn+ssh://[username]@svn.gna.org/svn/freeciv/branches/S2_1 svn+ssh://[username]@svn.gna.org/svn/freeciv/tags/R2_1_0_beta1

should do the trick.

The tag is the release, not a copy of it. It's preferred that tarball is built from clean tag checkout.

Mark as release versionEdit

Check out the tag as you would a regular branch.

Edit fc_version and remove the '+' (plus), to indicate that this is release code. Commit this to the tag.

DistcheckEdit

Run make distcheck in the root of the source dir and make sure there are no serious errors.

S2_5 and earlier Edit

(Since this is a clean checkout, you'll need to run ./autogen.sh and make first.)

S2_6 and later Edit

(Since this is a clean checkout, you'll need to run ./autogen.sh --enable-sys-tolua-cmd first. If you don't have tolua in your $PATH, you need to specify its location on configure line.)

Prepare source archivesEdit

Main source archiveEdit

If building S2_5 or earlier, first compile the source code with "make".

Create distribution archive(s) with "make dist".

Currently (since 2.4) we distribute .tar.bz2 and .zip, and all necessary archives drop out of "make dist".

Supplementary graphics archiveEdit

Since 2.4.0, we distribute the material in data/graphics/ from which the actual game graphics were manually derived, in a separate tarball for reasons of size.

Creating this tarball is currently a manual process. In a separate directory from where the main tarball was prepared, do something like:

svn export svn+ssh://[username]@svn.gna.org/svn/freeciv/tags/R2_4_2/data/graphics freeciv-2.4.2/data/graphics
tar cf freeciv-graphics-materials-2.4.2.tar freeciv-2.4.2
bzip2 -9 freeciv-graphics-materials-2.4.2.tar

Upload source archivesEdit

GnaEdit

Upload these files to download.gna.org. Put a copy in /upload/freeciv/stable - e.g. scp freeciv-2.5.5.tar.gz [username]@download.gna.org:/upload/freeciv/stable/ (and similar for the other formats). (Betas and release candidates go in /upload/freeciv/beta instead.)

Now update the checksums files (MD5SUM and SHA1SUM). Download each from the server, add the sums for all the archives (something like md5sum freeciv-*2.5.5.* >> MD5SUM, and sha1sum for SHA1SUM), and re-upload the checksum files.

SourceforgeEdit

Upload the files to Sourceforge. This takes a bit of doing. Log in with your account on their website, go to our project page, and go to the Files page where you create a new folder for the release, e.g. /Freeciv X.Y/X.Y.Z/ .

Next, create a file README.md briefly describing the release and linking to the NEWS on the wiki. See existing releases for examples. Upload this to the folder you just created.

Next, upload the release packages. You have two options to upload the files:

  • through a file transfer app such as scp or sftp - do something like scp freeciv-X.Y.Z.tar.bz2 [username],freeciv@frs.sourceforge.net:"/home/frs/project/f/fr/freeciv/Freeciv\ X.Y/X.Y.Z/" (details); or
  • through a web browser; use the "Add Files" option in the web interface using a modern web browser.

When you're done, click "Files" at the top right of the page to make sure the release is there.

For a stable release, use the web UI to mark the .tar.bz2 as the Default Download for Linux, BSD, Solaris, and Others (leaving Windows and Mac OS X alone; they'll be updated when the package maintainers upload their binaries; and don't touch Android as we have nothing appropriate for that platform).

Kick off Windows/Mac binariesEdit

Having made the source tarball, it's time for the package maintainers to do their thing.

Create tasks in GnaEdit

Create a task at Gna to track each of:

  • The Windows package, maintained by cproc at time of writing. (Example.)
    • (Here are some notes on how the Windows package is built.)
    • On download.gna.org, files go in packages/windows (both beta/RC and stable releases). On SourceForge, they go in the same folder as the source tarball.
  • The Mac OS package, maintained by bitaxis at time of writing. (Example.)

(The appearance of these tasks shouldn't come as a complete surprise to the package maintainers, of course.)

NotificationEdit

Notification goes in several places.

In the past, we have postponed some notifications until binary packages are available, on the grounds that most users will want the binaries; however these days we announce the source tarball immediately, and follow up in forums where that makes sense when the binaries are available.

When source tarball is availableEdit

i.e., immediately after the above:

Freeciv.orgEdit

The main website is kept in Gna svn.

  1. Review any previous unpublished updates to svn and work out what to do with them.
  2. index.html: Add a news item (removing any old ones making the news section too long).
  3. index.html: Update the version number and release date near "Download Freeciv".
  4. download.html: Update all references to the overall release number and source distribution (search for the old version number). Six in "Source Code", two above that.
  5. download.html: Uncomment the "Windows packages for the latest release are not available yet" notice, if necessary.
  6. js/freeciv.js: Maintain the version numbers in commented-out code (to avoid mishaps if we ever enable it).
  7. Test the download links on download.html!
  8. Commit to svn.
  9. Update the website on colossus from svn (requires a login to colossus).
WikiEdit

(This should be done at the same time as the main website.)

  1. Add the news item from the website to Template:News (not used for much). Also edit News archive, per the instructions there, including moving to the appropriate yearly-news page, e.g., 2015, if this is the first news this year.
  2. Add the NEWS-x.x.x page you created previously to Category:NEWS and link to it from NEWS.
  3. Change Template:Version / Template:Released (or Template:Version-beta / Template:Released-beta for a beta/RC) to the correct version and date.
IRCEdit

Change the topics of #freeciv and #freeciv-dev with the new version.

MetaserverEdit

The metaserver needs to be changed to announce the new version. Choose the appropriate "follow tags", e.g. 'stable' for a stable tarball release. Only some people have access to do this.

EmailEdit

Email should go to freeciv-dev@gna.org and freeciv-announce@gna.org. Use bcc on all of them with reply-to to freeciv-dev (we don't want others spamming these lists with replies). The email is basically a text version of the news from the web site.

Release announcements are pretty dull so it's easy to just copy an old one and change the versions and dates. (If binaries aren't available at the time of doing this, just say "Binary versions for other platforms will be listed as they become available" or some such.)

ForumEdit

Start a new thread at the Announcements forum.

TwitterEdit

Twit about the new release @freeciv.

When binaries are availableEdit

Freeciv.orgEdit
  1. Review any previous unpublished updates to svn and work out what to do with them.
  2. download.html: Comment out the notice about old Windows packages, and update the version number (in nine places).
  3. Test the download links on download.html!
  4. Commit to svn.
  5. Update the website on colossus from svn (requires a login to colossus).
ForumEdit

Follow up in the forum thread that binaries are available.

TwitterEdit

Reply to the original release tweet, announcing the binaries.

SourceforgeEdit

Double-check the binaries are marked as being the latest file for their platforms, if appropriate. (Package maintainers will probably already have done this when they uploaded.)

MetaserverEdit

Again, for each binary release, the metaserver needs to be changed to announce the new version. Choose the appropriate "follow tag" for the kind of binary and release. Only some people have access to do this.

Major releasesEdit

The first major release in a series will always be different and have its own quirks. Here are a few hints for things that need to be considered in the months running up to the first release (not an exhaustive list; see above for some more):

  • Decide when network protocol and file formats are to freeze. Typically we raise a task for each, to hook blocking bugs up to.
  • Make sure docs are up to date:
  • Translations:
    • Many translators work on stable branches only, so at some point translations need to be copied forward to the newer branch. But take care not to overwrite any newer work that some translators may have done on that branch.
    • Once per release cycle, update the table on Translations to reflect which translations have been touched recently and which are considered orphaned.
  • Identify any decisions that need to be made about binary packages, such as optional new dependencies, and decide what configuration(s) will ship.
  • Make sure traces of FREECIV_DEV_SAVE_COMPAT are removed (GNAPATCH#6154).

Release CandidateEdit

See also: Release Cycle

A major release leaving beta stage should be preceded by at least one release candidate (RC). The final release is made in the case no (new) showstopper bug is discovered within 7 (seven) days. If a showstopper bug is discovered, this bug should be fixed and a second release candidate should be released as soon as possible. Repeat until a full seven-day period can be completed.

The definition of a showstopper bug is one that prevents a large group of players to build, start, or complete the game.

During the release candidate phase, any code or rules changes are strongly discouraged. On the other hand, updates to documentation and translations are equally strongly encouraged.

Release candidates should be built IS_BETA_VERSION=0 in fc_version. For the first (and subsequent) release candidates, the DEFAULT_FOLLOW_TAG in fc_version should be changed from something like "S2_5" to "stable", and the --with-followtag in win32/installer/Makefile from "win32-S2_5" to "win32".

Around Wikia's network

Random Wiki