Developing Freeciv |
---|
Release process[]
Freeciv is using git branches and tags in the release process. Development of new features takes place on the main branch. When a new feature set on main is deemed feature complete enough for general use, the main source tree will be branched into a "stable" branch, named with the pattern SX_Y where X_Y is the major version number, e.g. S2_6. 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. Underscore is used also to separate "beta" and "RC" labels from the main version number in the tag name; ex. R3_0_0_beta1, R3_0_0_RC1
Before the release[]
Release ticket[]
In osdn, as well as a target version, we usually have a ticket for the release, as somewhere to accrue notes about timing, details of Windows builds, particularly important bugfixes, etc. (Example.)
Translations and string freeze[]
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[]
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[]
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 files[]
Check for and commit any translations -- check for posts to freeciv-i18n, pending translation Pull Requests on github, and to other upload locations listed in Translations.
Run "make update-po" in each subdirectory under translations/. Commit the changes.
NEWS[]
Review the commit logs from the previous release version and associated tickets; from this the news can be created. NEWS goes into a wiki page named something like NEWS-3.1.3. (If this has been started before the day of the release, make sure it's up to date.) This is a natural time to also update the People page.
- 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.6.x compared to 2.5.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.)
Docs[]
Make sure the NEWS and NEWS-x.y files in Git are up-to-date with the NEWS page(s) on wiki. A script which helps scrape and format NEWS from wiki can be found in git as doc/fetchnews.pl.
If you don't use fetchnews.pl, but just copy & paste from the wiki, you may encounter problems with wikia refreshes constantly clearing your selection when you try to select the text to copy. As a workaround, you can go to edit mode and without doing any actual edits open the "preview". On that preview screen I've found selection to work all right.
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 Git on the appropriate branch, and make sure it's listed in Makefile.am and meson.build (osdn#41727 has an example), and ensure it's cross-referenced from NEWS. (This file does not exist on main branch, and would have nothing to say for beta1.)
Consider whether doc/FAQ needs refreshing from wiki (using doc/generate_FAQ.pl to scrape it). At least update the embedded version numbers (it would be silly to release 2.6.2 with doc/FAQ saying "The current stable Freeciv version is 2.6.1.")
It's probably a good idea to git push
to Github at this point; nothing done up until now commits you to going through with the release, but everything after here should be kept local so it can be rolled back if necessary.
Bump version, mark as release version[]
Edit fc_version
to (a) bump the version number (b) remove the "+" from VERSION_LABEL, starting from 3.0.5 also (c) set RELEASE_DATE and make sure RELEASE_TYPE gets correctly set (either automatically, or in some cases manually). Commit this locally to the branch.
ChangeLog[]
You need to be in an up-to-date working tree for the relevant branch.
First available in 3.0.2, ./scripts/refresh_changelog.sh should do the ChangeLog update automatically, but does not commit it.
Older instructions:
Updating the ChangeLog in git can be done through the git log
command. Do something like
git log --no-decorate --pretty=medium R2_6_1^..HEAD
where "R2_6_1" is the last release's tag. Paste the output into the top of the ChangeLog file.
- This should do the right thing even if there was a merge bubble around the last release (because someone committed to the branch during release). It also works for non-linear history.
- However, if the ChangeLog had been updated since the last release, use the commit hash of its last entry instead.
Committing[]
The ChangeLog should be the very last thing to be committed before the release, so that it includes info about all the other commits.
Tagging[]
Create the release tag (in your local repository).
git tag -a R2_6_2
(If the release build goes horribly wrong or needs postponing, it will be possible to delete this tag and any related commits and try again, until the later step where the tag and commits are pushed to Github.)
The convention is that "beta" label in the tag is written in lower case ("R3_0_0_beta1"), but "RC" label in upper case ("R3_0_0_RC1")
Make fresh build tree[]
It's preferred that tarball is built from clean tag checkout. Create a fresh working directory (git worktree
needs Git ≥2.5).
git worktree add --detach ../2.6.2-git
(../2.6.2-git
is the fresh working tree from which the tarball will be built.)
Mark branch as development code[]
Still on the development branch, edit fc_version
to add the "+" back to VERSION_LABEL, and make sure that RELEASE_TYPE gets set correctly, and RELEASE_DATE not at all (development builds should not have the date set to previous stable release) Commit this to the branch immediately. (This will be the first commit contributing to the next version.)
Distcheck[]
Go to your new work tree:
cd ../2.6.2-git
Run make distcheck in the root of the source dir and make sure there are no serious errors.
(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 archives[]
Main source archive[]
Create distribution archive(s) with "make dist".
From 2.6 (and since 2.4) we distribute .tar.bz2 and .zip. Starting from 3.0 we distribute .tar.xz and .zip. All necessary archives drop out of "make dist".
Supplementary graphics archive[]
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 the same worktree from which the main tarball was prepared, do something like:
2.6:
git archive --format=tar --prefix=freeciv-2.6.2/ HEAD data/graphics | bzip2 -9 >../freeciv-graphics-materials-2.6.2.tar.bz2
3.0:
git archive --format=tar --prefix=freeciv-3.0.0/ HEAD data/graphics | xz -9 >../freeciv-graphics-materials-3.0.0.tar.xz
Push the tag[]
Having done any testing you feel necessary to satisfy yourself that this is good to release, push the tag and the relevant development branch to Github.
git push origin S2_6 R2_6_2
If someone has committed to the development branch in the meantime, you may have to create a merge commit on S2_6
. Alternatively, if you prefer, you can delete your local tag and relevant commits and go back to "Bump version" to redo the release.
You may at this point wish to delete the worktree (just deleting the directory is sufficient, git worktree
will clean up later).
Upload source archives[]
freeciv.org[]
Upload these files to files.freeciv.org. Put a copy in /srv/files/public/stable - e.g. scp freeciv-3.1.3.tar.xz [username]@gardens.freeciv.org:/srv/files/public/stable/
(and similar for the other formats). (Betas and release candidates go in /srv/files/public/beta instead.)
Now update the checksums files (MD5SUM, SHA1SUM, SHA256SUM). Download each from the server, add the sums for all the archives (something like md5sum freeciv-*3.1.3.* >> MD5SUM
, sha1sum
for SHA1SUM, and sha256sum
for SHA256SUM), and re-upload the checksum files.
Sourceforge[]
Upload the files to Sourceforge. 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. (Mark it as "Exclude Stats" in the Sourceforge web UI.)
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.xz [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.xz 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 binaries[]
Having made the source tarball, it's time for the package maintainers to do their thing.
Create tasks in osdn[]
Create a task at osdn to track each of:
- For freeciv-2.6 only: The official (msys1) Windows package, maintained by cproc at time of writing. (Example.)
- (Here are some notes on how the Windows package is built.)
- On files.freeciv.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 official download location for the msys1 ("gnuwin32") build environment (referenced in installer Makefile) is Sourceforge (here). Ensure it contains the environment used for this release. (A copy may already be on files.freeciv.org.)
- The msys2 Windows package, expected to be built by cazfi. (Example.)
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.)
Ticket tracker maintenance[]
In osdn, make the milestone "done" in it's very own view. Marking milestone "done" from the milestone list has not been working for me. In Redmine, under Settings / Versions, mark the status of the released version as Closed so that no more tickets get targeted at it. Make sure there's an open record for the next version (probably this will have been created already).
Update packages on Flathub[]
Freeciv maintainer with access to freeciv.org's flathub repositories need to update flatpak recipes there.
Notification[]
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 available[]
i.e., immediately after the above:
Freeciv.org[]
The main website is kept on Github. You may prepare and test the announcement commit in advance in a local branch to make things simpler at release time.
- Review any previous unpublished updates to Git and work out what to do with them.
- index.html: Add a news item (removing any old ones making the news section too long).
- index.html: Update the version number and release date near "Download Freeciv".
- 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.
- download.html: Uncomment the "Windows packages for the latest release are not available yet" notice, if necessary.
- js/freeciv.js: Maintain the version numbers in commented-out code (to avoid mishaps if we ever enable it).
- Test the download links on download.html!
- Push to Github.
- Update the website on gardens from Github (requires a login to gardens). Ensure group ownership/permissions are correct.
Wiki[]
(This should be done at the same time as the main website.)
- Add the news item from the website to Template:News (not used for much). Also edit News archive, per the instructions there. If this is the first release this year, follow the instructions in comments in the old year's page (e.g. 2020) to start a new year's news archive page.
- Add the NEWS-x.x.x page you created previously to Category:NEWS, link to it from NEWS, and ensure it references the appropriate template at the top (e.g.,
{{NEWS info 2.6}}
). - Change Template:Version / Template:Released (or Template:Version-beta / Template:Released-beta for a beta/RC) to the correct version and date.
IRC[]
Change the topic of #freeciv with the new version (you'll need privilege from ChanServ). (Also update #freeciv-dev if necessary, e.g. when moving into beta, RC, or stable phases.)
Metaserver[]
The metaserver needs to be changed to announce the new version. Choose the appropriate "follow tags" in metaserver/versions.php
for source releases, e.g. 'stable' for a stable tarball release (but leave the Windows-specific ones alone). Only some people have access to do this.
Email[]
Email should go to freeciv-dev@freelists.org and freeciv-announce@freelists.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.)
Forum[]
Start a new thread at the Announcements forum.
Twitter[]
Twit about the new release @freeciv.
Mastodon[]
Announce the new release @freeciv@fosstodon.org
When binaries are available[]
Freeciv.org[]
- Review any previous unpublished website updates in Git and work out what to do with them.
- download.html: Comment out the notice about old Windows packages, and update the version number (in nine places).
- Test the download links on download.html!
- Commit and push to Github.
- Update the website on gardens from Github (requires a login to gardens).
- Update mapping between freeciv releases and msys2 environments at files.freeciv.org/packages/windows/msys2/Readme. This should always be the same as one mentioned in the README.msys2 of the source tarball. This requires login to gardens.
Forum[]
Follow up in the forum thread that binaries are available.
Twitter[]
Reply to the original release tweet, announcing the binaries.
Sourceforge[]
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.)
Metaserver[]
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 releases[]
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:
- Editing rulesets: create a new "How to update a ruleset from 3.x to 3.y" page
- Editing tilesets: create a new "How to update a tileset from 3.x to 3.y" page, if necessary
- Lua reference manual
- doc/README.packaging
- doc/README.modpack_installer, and Creating freeciv-modpack content
- 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. (Traditionally around x.x.0 time.)
- 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 (osdn#45449).
On release day[]
There are some things that have to be done at the time the first stable release, x.x.0, is shipped.
- If the FAQ has had major revision, you probably had a new version as a separate wiki page. Move the old one to e.g. FAQ 2.5 (don't move the Talk page), and move the new one to FAQ. TODO: We should stop moving pages around and breaking links to specific version. Instead we should just have FAQ as a redirect to version specific FAQ of current version.
- Add the previous major version to Old downloads, including creating a page like Template:Version2.5 to record the last version in that series.
- On the website in git, move this version's details to the 'stable' section and comment out or remove the 'beta' section.
Once the release is done, make sure later branches are ready for their eventual release; in particular, make sure NEWS and doc/FAQ reflect changes in the newly-stable release.
Release Candidate[]
- 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.
a.b.0 release[]
For the very first stable release (".0" -release) from a series, the DEFAULT_FOLLOW_TAG in fc_version should be changed from something like "S3_0" to "stable", and the --with-followtag in windows/installer_msys2/Makefile from "windows-S3_0" to "windows". (We used to do this for the release candidates already, but then earlier candidates would not get informed about later candidates that are not yet the "stable" release)