Public release: procedure

Designating a public release

Current project convention is that no particular version number is planned ahead. Instead, when the changes are pushed to master branch, an effort is made to keep the branch in semi-releasable state. That is - regardless whether these changes complete certain feature, or only part of it, they should be self-sufficient in terms of implementation, i.e. already work on their own.

The time of next release may be determined by two reasons:

• There is already an abundance of changes that could be interesting for end-user (new functionality, bug fixes, improvements);
• A notable amount of time has passed and there are any notable changes; the period of time can be predetermined (e.g. 4-6 months).

NOTE: code cleaning and refactoring is only then counts towards release decision when it noticeably improves program performance.

Release preparation procedure

1. Determine version number for this release.
2. Fork the release branch to work on finalizing the release.
3. Adjust named constants in code for the chosen version number.
4. Make beta release for the public testing and gathering opinions.
5. Apply fixes and minor improvements to reach stable and usable program state.
6. When ready, make final release.

Determining version number

New version number is determined depending on quality and quantity of changes new version contains. There are no strict formula here, but in general if there are major features that add absolutely new functionality, then it is considered "major" release, and version should be equal to previous public release version with major (second) number incremented, and minor (third) and build (fourth) numbers reset, for example:

3.4.5.10 -> 3.5.0.0

If there are only minor changes, or simply fixes, the it is considered "minor" release, and version should be equal to previous release version with minor (third) number incremented, and build (fourth) numbers reset, for example:

3.4.5.10 -> 3.4.6.0

IMPORTANT: if the new minor version was already in use during the development, serving to indicate WIP builds, and it was decided that upcoming public release is going to be minor one, then same minor version is kept and only build number is incremented once more to distinct first public beta release from the latest development build, for example:

3.4.5.10 (alpha) -> 3.4.5.11 (beta 1)

Forking release branch

As soon as dev team decided it is time to prepare public release, a branch is forked from the top of the master branch. By convention the branch should be named "release-X.X.X" (where X.X.X are first three version numbers).

Since that moment all fixes and last improvements related to release should be done in that branch. The further development, unrelated to this release, can be continued in master branch at the same time.

In the end, release-X.X.X branch should be merged back into master, carrying over the released state, where applicable. Of course it is allowed to merge it to master several times if release preparation took longer than expected, and you want to have those fixes in master immediately.

Adjusting version-related constants in the code

There are number of constants in the Editor and Engine code that may have connection to the release version in their names, such as those that define data format variant, script API version, etc. If added/altered during development process, they may keep WIP version number in their names. If the determined version number is different from the one used during development, then those constants may end referencing version that was never officially released.

That is not necessarily essential for all of them, but still recommended to adjust their names to match actually released version if possible.

The most important case is ScriptAPIVersion enumeration in the Editor, that determines available options for the "Script API level" and "compatibility level" game properties. If incorrect WIP version will be left there, it may confuse end-users and probably cause buggy behavior. Along with this enumeration, following related macros also must be checked in the built-in script header in the Editor:

• SCRIPT_API_vXXX
• SCRIPT_COMPAT_vXXX
• STRICT_IN_vXXX

where XXX is the number of the WIP version you had during development.

Marking beta and release candidates

There are two things you can do to emphasize the beta state of the released build.

1. In the Editor set AGS.Types.Version.IS_BETA_VERSION variable to 'true' (do not forget to change it back to 'false' for the final relase);
2. In the version.json script (in the repository root) assign "versionSp" string to something around the lines of "Beta", "RC", and so on - that will add same tag to the Editor installer and distribution packages.

Final release checklist

1. Update brief release information in the Editor (WelcomePane.cs). This is important for major releases, can skip for minor releases.
2. Update Changes.txt using Git history. Usual convention is to not mention internal changes, invisible to end-user.
3. Update Credits.txt with new contributor names (if any).
4. Update OPTIONS.md if there were any changes to game config/command line parameters.
5. Update the Manual:

• New Script API and other articles related to new features;
• If it is a major release and/or has important changes, write "Upgrading to XXX" article (see existing ones for example);
• Synchronize developer/contributors list in "Credits" article with Credits.txt;
• If using new non-code material from other contributors (game templates, icons, libraries etc) add them to "Credits" article.

6. Double-check that IS_BETA_VERSION in AGS.Types.Version class of the Editor is "false".
7. Do not forget to increase the build (fourth) number in version one last time.
8. Create new git tag at the last commit belonging to this version development (e.g. "v3.4.5.12") and mark it as "release".