Workflow

This page describes the workflow from a concept until release. Try to follow this when developing a new feature or releasing a new Empires version.

If you're working on something that impacts user experience or gamedesign, please look at the Guiding Principles

Creating an Issue

To ensure we don't duplicate effort and to allow team members to see what we're working on we add a short description of the thing we're trying to fix / achieve to an issue on the internal issue tracker.

An issue is a new feature, known bug, known exploit or anything that requires developer work/discussion.

When adding an issue, try to stick to formulating it as a user story. This makes it easier to evaluate whether a proposed change actually fixes the issue. To help discoverability you can add relevant tags.

If you plan on working on the issue yourself, be sure to assign yourself to it. For more information on how you can effectively use issues you can refer to the official issue documentation.

Cloning the Relevant Repository

If you've already performed this step in the past you can ignore this section

1. Make sure you have an account on the internal gitlab and have received the appropriate permissions.
2. Make sure you have added your public key to your acccount.
3. Clone git@git.empiresmod.com:empires_assets/empires_build.git in a location of your choosing. Make sure you have at least 30gb free space.
4. Double click the setup.bat file on Windows or the setup file on Linux and wait for the process to finish.
5. Double click the preview.bat file on Windows or the preview file on Linux and wait for the process to finish.
6. You should now have a development version of Empires you can run in your preview folder.

C++ development setup

To get started with C++ development you just need to checkout empires_main and copy the file from steam (Steam\steamapps\common\Empires\empires) to empires_main/mp/game/empires. For more details on Visual Studio setup check the README in the repo.

If you also want to make changes to assets_base and empires_scripts and test them with your C++ changes, you can best checkout those repos next to the empires_main repo and then edit empires_main/mp/game/empires/gameinfo.txt

   SearchPaths {
     game+mod				|gameinfo_path|../../../../assets_base   // <<--- Add this 
     game+mod				|gameinfo_path|../../../../empires_scripts // <<--- Add this 
     game+mod				|gameinfo_path|custom/*

Creating a New Branch

1. Figure out which repository you should be editing. The repos folder contains a list of all the repositories you have access to.
2. Figure out if the issue you're working on should be categorized as a bugfix or as a feature. Bugfixes are changes which don't change the intended behavior of the game but purely fix a previous mistake. The rest are features.
3. Create a new branch named bugfix/your-description or feature/your-description based on the master or develop branch. (Not all repositories have a develop branch, use master in that case)
4. Start working on this branch and regularly commit your changes. You can create a new preview for testing by clicking the preview script again. This will include the changes you just made.

Creating a Merge Request

1. Push your changes to the remote server. In the console output you'll see a link you can visit to create a new merge request. If there is no link you can also manually go to the project in gitlab and click on the New Merge Request button under the Merge Request tab.
2. Give the merge request a descriptive title and mention the issue number in the description as follows: #123
3. If your changes are not yet done or they don't yet pass all the build tests it's recommended to prefix the name of your merge request with WIP: . This is a signal to reviewers that they should wait a bit until they spend time reviewing the change.
4. Try to describe in the description field what you had to change and why.
5. Configure the merge request to delete the source branch when it is merged. If you don't know how to do this you can skip this step.

Reviewing a Merge Request

1. Start with a code review. A code review is meant to improve code quality and distributes knowledge about the codebase between team members. Code review is not meant to catch errors / bugs although it's not a problem if it does. Try to review the code on the following areas:
   • Feature Completion (Does this change actually address the issue referenced)
   • Side Effects (Does this change only impact the issue or does it negatively influence other features)
   • Readability and Maintenance (The codebase is now 10+ years old and will probably have to be used for a long time, make sure we don't reduce our velocity)
   • Consistency (Does the code look the same as the surrounding code and does it solve problems in the same way as we do elsewhere)
   • Performance (If we can improve performance without impacting Readability and Maintenance or other side effects we should probably do so. When in doubt, measure the performance using profiling).
   • Simplicity (Simpler code is usually better, even when it reduces performance)
   • Reuse of Existing Code (A lot of our code looks copy pasted, we can reuse a lot more than we currently do. Try to review whether there is code that can be reused)
   • Source Files (Make sure we have source files for all compiled assets that are in the merge request)
2. Test the code. Check out the code and create a preview to test with on a local listen server.
3. If everything works as intended add a thumbs up smiley as a response.

Merging Requests Into Alpha

You generally want to merge bugfixes as fast as possible. If you plan on releasing another point release (2.14.3 -> 2.14.4) you should probably wait with merging new features. Merging new features usually results in more bugs so queuing them for the next minor release (2.14.3 -> 2.15.1) is advised.

Once the Continuous Integration has been run after the merge you can press the play button on the empires_build Pipelines tab for the newly created version. After that has finished the alpha branch on Steam should have the latest development build. If you don't have the alpha branch on steam, please ask for the password on Hipchat.

Preparing a Beta Release

1. Update the version in the alpha branch. Never release the game twice with the same version number, it'll cause weird issues if people try to connect to servers with the wrong version.
2. Add the changes in this release to the Changelog.
3. Push the new release to alpha.
4. Create a new merge request from alpha to beta. Make sure to uncheck the box that removes the source branch.
5. Test the alpha with some developers. If you encounter issues, fix them before releasing to beta.

Preparing a Full Release

1. Merge the pull request from alpha to beta
2. Schedule a beta test and a beta server.
   1. Post the beta test on the forum
   2. Post the beta test on reddit
3. If you encounter issues, prepare a new Beta Release with a new version number until you're ready to release it.

Releasing a New Version

1. On the Steam Partner page:
   1. Publish the latest beta to the default channel for the server
   2. Publish the latest beta to the default channel for the client
   3. Update the dedicated server version for the client
   4. Publish the store changes for the server
   5. Publish the store changes for the client
2. Restart the Lobby.
3. Publish the changelog as a steam announcement
4. Publish the changelog to Reddit
5. Publish the changelog to the forum
6. Publish the changelog to Moddb
7. Publish the changelog to Discord