Release instructions

[Semphriss]

Initiated by #2117 _{(and restructured by me and my passion for essays)}

When comes the time to produce a new release of SuperTux, the steps are only remembered by memory, which can lead to loss of information (forgetting a step, replacing a key person and the new project lead doesn't know how it's done, etc). This is a proposal to establish a list of things to do for a release, which would be kept in the repo and would server as a reminder for ourselves as well as future maintainers, so releases happen as smoothly as possible.

The current plan

• Await an appropriate time to do a release. (When should releases be done?)
• Enter a string freeze (Do not accept any contribution which change translatable strings in the game, as the potential new strings won't have time to be translated), pack the strings (steps?), upload them on Transifex and notify translators
• Enter feature freeze (Do not accept any contribution that adds to the game, as they might add new bugs), package and post a beta and/or a release candidate ("rc") (difference?) (steps?), and post it on GitHub only.
• Await bug reports. Only accept PRs that fix reported issues and that do not add features or add/change strings. Wait 2-3 weeks, to give translators enough time to notice the notification (especially at times around Christmas) and for testers to discover enough bugs. Test extensively.
• Prepare an announcement text for the various services: GitHub, supertux.org, Twitter, Steam, Google Play. (others? What should be put in the announcement for each service? What are the guidelines?)
• Fetch the translated strings from Transifex and emplace them in the game. (steps?). Commit and push the translations.
• Create a new release by creating and pushing a tag on git, following the format "vX.Y.Z" where X, Y and Z are the appropriate numbers. (How to decide which numbers?)
• Let GitHub build SuperTux through the CI.
• Once the builds are complete, do an announcement on GitHub, supertux.org and Twitter, and update the builds on any team-controlled repository (Steam and Google Play) and post the announcement on each of the service.
• Lift the feature freeze and the string freeze. Any new contribution will be part of the next release.

Is this plan complete? Does it need improvements?

Some issues I've found (copy-pasted from this comment)

• Steam: How should those be handled? Builds may have a review delay, and announcements may or may not be produced each release.
• GitHub Actions already handle uploading releases to GitHub, no action is needed. Should we also setup a CI for other platforms? For the website? How would we do that?
• How do we handle announcements on GitHub? (Do we do announcements at all?)
• Speaking of which, what do we put in the announcements? (Especially given the constraints of some services, like Twitter's length limit)
• Should we contact maintainers for various Linux distros, *BSD packagers, Brew, WinGet and more to handle their updating of SuperTux? Should we use the CI to help them perform the updates automatically? Should we implement service-specific actions in our CI? How should we do it for each maintainer?
• Google Play and other platforms with specific needs: How should their packaging be handled? Do they need specific build options? Always, conditionally? If conditionally, when to set a given option?
• Related to above: Should we strictly stick to CI builds to be distributed, or should we allow someone to compile SuperTux on their own computer for distribution? This can be necessary sometimes, but it will reduce the assurance that the builds are reproducible with a known, easy-to-find source code + build instructions.

All of this has to be decided while keeping in mind plenty of people will replace each other during SuperTux's history, so we shouldn't design this just for ourselves. If I (or anybody) happens to be absent for a release, for any reason, the team should be able to proceed without the missing people.

[Mathnerd314]

R.e. Steam I think the main goal is to make consistent quality releases, so that we don't get negative reviews. Since we have no QA department the only way to do testing is to release the game and let people find bugs themselves. But if we do that on a Steam release we'll get negative reviews.

So the beta should address that, something like:

• Fork master as a new release branch, release as a beta on supertux.org and Github
• Wait 4-6 weeks for translations, bugs, etc. to show up and get merged to the release branch
• Release final version on steam, supertux.org, etc.

[Semphriss]

Proposition

This is the document I'm working on for the WIP SuperTux Meltdown, so I thought I might share it here to help make things progress a bit.

I've adapted the document to fit the context of SuperTux; the original document (unpublished at time of writing) also instructs to follow semantic versioning and to write and follow a roadmap. I've removed both of these; the former, because although I believe SuperTux should be versioned properly, I don't want to defend that alone if nobody else wants to; the latter, because I believe the development process is too informal for such a document to be useful. I don't mind re-adding the latter if turns out to be interesting, but I thought it'd be more restrictive than anything.

The specific steps to perform releases follow.

---

When comes the time to do a release:

1. Determine the new version string for the upcoming release. (vX.Y.Z)
2. Enter string freeze and feature freeze. Translatable strings may not be modified until the string freeze is lifted, and no features may be added to the master branch; only bugfixes simple enough not to risk introducing other bugs (that is, nothing that changes how something works) may be added.
3. Notify the contributors that a new release is in progress. The notification should reach at least translators and testers.
4. Wait as long as reasonable for contributors to fix bugs and translate strings. Leave enough time for all contributors to notice the planned release and to translate the game and fix bugs. Pay special care in times of holidays, vacation, or any other time where people might not be available. Generally, a duration of a month should be enough.
5. During that time, the team may, at its discretion, produce release candidates to help contributors find errors in cleaner builds, or third-parties to perform tests in their environment. Release candidates are generated by doing steps 7 to 11, but by appending -rc1 to the version string. The version used is the one of the upcoming release. Subsequent release candidates will follow the same steps but use the suffix -rc2, -rc3, and so on. For consistency, do not use -alpha, -beta; if those are to be used, they should be a) properly defined, b) serve a purpose and/or carry a signification for third-parties, and c) be clearly distinct from release candidates in terms of purpose.
6. If both translations and bugfixes seem to finish their activity, and all active translations are complete and no other bug can be found within a reasonable time frame, the release can be performed.
7. Prepare an entry for the changelog. The entry should announce the release to the public in one or two sentences, followed by a list of the most significant changes for users (important new features, major bugfixes, etc) since the last full release. If it is a regular release, add the entry to the changelog and commit it; if it is a release candidate, do not add the entry yet, but prepare a draft. In any case, document any known bug in the changelog, and specify if any cannot be fixed for the upcoming release.
8. Tag the latest commit on master as 'vX.Y.Z', replacing X, Y and Z by the major, minor and patch versions, respectively. Make the tagging message "Release X.Y.Z" (without 'v'). Add -rcX if necessary. Example command: git tag v0.0.0-rc0 -m "Release 0.0.0-rc0"
9. Produce release builds from the tag for all supported platforms. It is strongly advised to use a CI system as this helps for verifiability. The compilation steps as well as the settings to use for release builds should be documented in INSTALL.md.
10. Do a GitHub release. Put as description the text done at step 7. If this is a release candidate, put it as a draft; make sure the description specifies that it is a release candidate. Make sure to include any build produced in step 9, including source builds (GitHub default source archives don't include submodules; custom sources archives should) and documentation artifacts, if any.
11. Notify any place of interest for contributors, such as community chats. Do not post an announcement for the general public. This is to give an opportunity to have packagers that are available at the time to prepare the release for their channels. Note that this is the last step for release candidates.
    • Places of interest for contributors are any internal and community chats (IRC, the forums, Discord, etc.)
12. Notify any place of interest for the general public. Update any place controlled by the team in descending order of notability. Update the website (supertux.org) in first, as the announcements on other platforms will link to the website. If the game is particularly popular with a certain distributor, update that place in priority. Let packagers and the community update the places they control as they see fit.
    • Places of interest for the general public include any social media controlled by the team that isn't defined at step 11 as a place of interest for contributors, such as Reddit, Twitter, and distributors announcements (Steam, Google Play, etc.)
13. Lift the string freeze and the feature freeze. Any subsequent commit will be part of the next release.

---

Notes:

• I intentionally did not specify what should the announcements for the various places contain; I preferred to leave the freeedom to the team to decide about that.

Please send feedback on this; is anything missing? Is anything superfluous? If it seems all good, please leave a reaction of some sort, just to know that this proposal has been seen ;).

[Mathnerd314]

Yeah, the terminology has been inconsistent. Mostly we've used "stable" / "unstable" to distinguish some level of playability. But git master has always been pretty playable so this distinction isn't useful IMO.

As far as tobbi's releases (0.6.0 and after) they seem to be following Wikipedia, insofar as it goes alpha->beta->candidate->release and there are no new levels added in those transitions. I think he did an alpha for 0.6.0 because it had been so long since a release.

I think we can standardize on two betas though.

[Semphriss]

Should I both adapt the document to use beta instead of rc and to instruct to produce two betas per release? I initially thought to not specify the number of pre-releases, but if two pre-releases are generally the best idea, I can specify it as such.

[Mathnerd314]

Yeah, we release one beta that's just a snapshot of master, one follow-up that fixes all the reported bugs, and then release it as a real release if no more bugs. If there's more bugs in the second beta then that's when we'd need more betas. That's also why it's not a "release candidate".

[Semphriss]

Alrighty, I'll update the proposal tomorrow when I'll have some free time.

[RustoMCSpit]

update?