Public release: procedure

Designating a public release

We distinguish following kinds of public releases:

• Alpha: this is when the current wip version already has a significant list of new features that may be interesting for users, but it's not considered complete or bug free.
• Beta: this is when the wip version is mostly feature complete, but is still in progress of testing, bug fixing, and improving existing functionality.
• Release Candidate (RC): this is when the version is fully feature complete and stable, but we might still want to keep it in public testing for a short while.
• Stable or Final: when the version is announced to be complete.
• Patches: when there are more mistakes found in this version, or there's a critical need of improving perfomance of existing features.

For each of those kinds we may have multiple public updates, identified with a 1-based number in the title. For example: Alpha 1, Alpha 2, Beta 1, Beta 2, and so forth. Only "Final" release is one of its kind. The Patches are named similarily (Patch 1, and on). There's no strict limit on how many updates can be in each stage (but if you are reaching high numbers, perhaps there are planning issues).

Setting up a version

The base version is defined by 3 numbers: A.B.C, where A is major, B is minor and C is "release" version number. The full version includes the fourth number D, which we call "build". The first three numbers must stay the same during particular version development. But the fourth number must increment with at least every public release. It may be incremented in between public releases too if wanted, there's no restriction on this. There's no real connection between this fourth "build" number and the release type: it's being incremented continuously, not trying to match a public release title.

Because the version number is required in several places in the code (in the Engine, Editor, make scripts, and so on), we have a way of automatically updating this number everywhere at once. For this purpose there's a version.json file in the ags repository root, and a Script/push_version.py py script, which copies the data from version.json to where necessary.

The contents of version.json are following:

"version": "A.B.C.D",
"versionFriendly": "A.B.C",
"versionSp": "",
"appID": ""

• "version" is the full 4-number version of the program;
• "versionFriendly" is the base 3-number version of the program;
• "versionSp" is the optional version subtitle (Alpha 1, Beta 2, Patch 3);
• "appID" is the Editor's program GUID, currently used when installing on Windows using an installer program. This GUID must be kept same for each base version number and changed when any of the base 3 numbers change. This allows to install updates and patches over previous ones in the system. The GUID may be generated, we recommend using InnoSetup's GUID generation for this.

After applying new data to version.json, run Script/push_version.py and these variables will be copied over to the source code files.

Additionally, for the Editor you may want to update two fields in the code:

1. AGS.Types.Version.AGS_EDITOR_DATE - displays the release date on the splash screen, and in the About dialog.
2. AGS.Types.Version.IS_BETA_VERSION - if set, then user will receive a "This is BETA vesion" warning upon starting the Editor. Do not forget to reset this to false for the final relase!

Changelog

The program's changelog is located in Changes.txt file.

The rule for filling it currently is this:

• Each version has its own dedicated changelist, which is written starting at least with the first public Alpha or Beta version, and is kept updated in-place as the development progresses towards the Final release. This changelist only names changes compared with the previous stable release (and not changes between Alpha and Beta updates).
• After the Final release was made, each next Patch will have its own separate changelist.

Making a public release

1. Ensure that version.json has correct base version numbers.
2. Increment the 4th version number (build number) for this release if it's not the first build for this version
3. Add a version subtitle if it's Alpha, Beta, RC or Patch; for Final release leave the "versionSp" field empty.
4. Run Script/push_version.py: that will copy the entered data to the respective project files.
5. Update Changes.txt and Credits.txt if necessary.
6. Make a commit with all these changes and push it to the remote AGS repository. We recommend to name such commits as "Updated build version (A.B.C.D)", but it's a mere formality.
7. Go to the "Releases" section of our repository's page on GitHub, and create a new release. The tag name should have a form vA.B.C.D, where A.B.C.D match the new release. Double check that you are creating this tag and release on a correct branch: it may be a master branch if you are developing there, or any of the previous "release-X.X.X" branches if you're making a patch, or a special branch. Write a brief description of this release, for example: list the changes since the last update, or post a link to the Changes.txt on corresponding branch.
8. As soon as you created a new Release on the GitHub page, our build server will receive a command to make all necessary packages and attach them to this release. These attachments should be safe for users to download.

The release-X.X.X branch

For each final release we create a "release-X.X.X" branch, where X.X.X are the first three version numbers.

The time for creating this branch is decided by the future development plans: if there's a plan to start working on a next version as soon as current one reached Beta or Release Candidate stage, then the "release-X.X.X" branch may be created that early. In such case, current version will be finished on this branch, while the master branch will be free to begin working on a new one.

If there's no hurry, then the release branch is created just before the Final release, or right after its done.

Such branch is never deleted, and kept for the version maintenance and bug fixing. All the following patches to the particular version should be done on its branch.

Final release checklist

1. Update the brief release information in the Editor (WelcomePane.cs). This is important for major releases, you can skip this for minor releases.
2. Update Changes.txt using the Git history. The usual convention is to not mention internal changes, invisible to the 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 the "Credits" article

6. Update the template sources: make sure their are saved in the latest version of the Editor, do not use deprecated Script API, and their settings are matching new defaults.
7. Double-check that IS_BETA_VERSION in AGS.Types.Version class of the Editor is "false".
8. Do not forget to increase the build (fourth) number in the version one last time.
9. If the "release-X.X.X" branch is not created yet, then create one.
10. Create a new Release on GitHub page and mark it as "Set as the latest release". Double check that you are creating this release on the corresponding "release-X.X.X" branch!