Creating a new release for xmage

This documents describes the steps that has a developer to to, to release a new public version of XMage. It distinguishes technically between a minor and a major release change. Minor release changes can be used if no changes are done concerning the interfaces of the client and server part of xmage. A major release prevents the usage of older clients with another major release number, so problems with that are prevented. Otherwise there are no fixed rules when and why to do minor or major releases.

Development steps

This part describes what to to on the development side, to create a new release.

1. Updating the version number

Change the version information in MageVersion.java. Normally MAGE_VERSION_PATCH for a major and MAGE_VERSION_MINOR_PATCH for a minor patch.

2. Update the DB version if neccessary

CARD_CONTENT_VERSION

The file CardRepository.java includes the CARD_CONTENT_VERSION number, that should be increased by 1, if the released version has a changed set of cards (nomally cards were added). So if the client connects to the new server version, he can request the updated card DB content and the client card editor is showing all available cards.

CARD_DB_VERSION

The file CardRepository.java includes also a CARD_DB_VERSION number, that needs to be increased, if the db structure of the cards DB was changed. That only happens rarely.

3. Update the version number in the project files (pom.xml) of all XMage projects

ONLY NEEDED FOR MAJOR RELEASE

For this change one can use the pearl script version-bump. If executed it shows the current version number (e.g. "1.4.32") and you are requested to enter the new major version number (e.g. "1.4.33"). The script than automatically updated all the pom.xml files of all projects with the new number.

4. Build an package

First take care, that the client card.db file is created/updated with the current release. The current version will be used in the created zip release file for the client and should be therefore up-to-date. Use the pearl script build-and-package to create a new release zip file. If the script was executed without errors, the new release zip file is created to your local drive.

5. Create a release tag for github

Create a new release tag with the new release number with a name in the form "xmage_1.4.32V0". The "1.4.32" means the major release number and the "0" behind the "V" indicates the minor release number. This tag is late needed to upload the new release file to github and allow users to download the new release from github.

6. Update the Release notes

Go to the Release-changes wiki page and create the section/page for the new release. Copy the gathered changes from the Features-and-fixes-not-released-yet page to the section for the new release. After that reset the Features-and-fixes-not-released-yet page to a initial state.

7. Create the release within github

Go to the previously newly created tag for the release and edit the tag. Add a release title (in the form "xmage_1.4.32V0" and add a link to newly created release wiki page or section in the description field. Upload the release zip file (that needs a little while) and publish the release if the upload is finished.

Distributing steps

This part describes what to to on the distibution to a XMage server side, to create a new release. The steps are based on the current xmage.de server installation and can vary, if you want to distribute the new version to another server.

1. Transfer the new version to the server

For this you only need the server folder of the release. So first unpack the release zip file and rename the server folder from "mage-server" to "mage-server1neu". Upload this folder to the folder your XMage server software is installed to on the server. For the xmage.de server this is the /usr/games folder. In this folder the currently active version is always named "mage-server1". So you add with this step a new folder called "mage-server1neu". With the next scheduled restart of the xmage server or if you execute the "xmage start" or "xmage restart" script, the script checks if there is a "mage-server1neu" folder. If so, the old active folder is renamed to "mage-server1[current date/time]" and "mage-server1neu" is renamed to "mage-server1". The needed DB files with user and user records data are copied from the old active to the new active version. Than the XMage server is started.

2. Update the \etc\init.d\mage-server-common

ONLY NEEDED FOR MAJOR RELEASE

The \etc\init.d\ folder contains 4 script files that are used to start and stop the xmage server.

mage-server
mage-server1
mage-server2
mage-server-common

However one of the scripts needs to be updated, if the major version number is updated. That the "mage-server-common" script. In the following line of the script, you need to update the version number of the jar file to the needed major version number.

	/usr/bin/cpulimit -l $limit -- \
	    /usr/bin/java $options \
	    -Djava.security.policy=./config/security.policy \
	    -Djava.util.logging.config.file=./config/logging.config \
	    -Dlog4j.configuration=file:./config/log4j.properties \
	    -jar ${base}/lib/mage-server-1.4.31.jar \
	    -adminPassword=[****] >/dev/null 2>/dev/null &
	;;

3. Update the specific server files of the new release

The server installation on xmage has three files, that are differnt from the default relase, that you need to update or replace on the server.

server.msg.txt

It includes the server specific messages, that are shown on the button of the xmage client and is locaed in the main mage-server1 directory.

config.xml

It includes the server specific IP and configuration. For a major release all the version numbers of the references jar files need to be updated. Also if new formats or game modes were added they have to be added to the specific file. Here for example you also decide, if the players can play agains the AI or not by allowing this play mode or not. It's located in the config sub directory.

log4j.properties

It defines what and how java logs problems. It's also located in the config sub directory.

4. Update the config.json file

To inform the client that there is a new release and define the name and the download URLs there is a config.json file on the xmage.de server. In the client teh URL to that file is configured and pointing to /var/www/html/xmage/config.json file on the xmage.de server. You need to update the content of this file to point to the URLs of the new release and chnage the "version" tag to be unique and correct for the new release.

It looks like this:

{
  "java" : {
    "version": "1.8.0_191",
    "location": "http://download.oracle.com/otn-pub/java/jdk/8u191-b12/2787e4a523244c269598db4e85c51e0c/jre-8u191-"  
  },
  "XMage" : {
    "version": "1.4.32V0 (2018-11-26)",    
    "location": "https://github.com/magefree/mage/releases/download/xmage_1.4.32V0/xmage_1.4.32V0.zip",
    "locations": ["http://xmage.de/files/xmage_1.4.32V0.zip"],
    "torrent": "",
    "images": "",
    "Launcher" : {
      "version": "0.3.8",
      "location": "http://bit.ly/xmageLauncher038"
    } 
  }
}

5. Upload a new version to the xmage.de server as alternate download source.

The complete release zip file should also be uploaded to /var/www/html/files to be availabel for users that can't use the github download.

6. Restart the server

It can be done manually by "xmage stop" followed by "xmage start" or by using only "xmage restart". Or sometimes it's also ok, to wait for the scheduled restart of the server. All the running games at that time are canceled. Now the new release is available and can be used.