Deployment

In this repository we can deploy to three different environments:

• deploy/faf - the FAF game type. This is the default release branch and is used by matchmaker
• deploy/fafbeta - the FAF Beta Balance game type. This branch only contains balance changes and bug fixes.
• deploy/fafdevelop - the FAF Develop game type. This branch contains all current changes that are in development.

All three branches originate from the develop branch, which is the default branch of the remote on Github. Pushing commits towards any of the deployment branches is sufficient to trigger a deployment to the given game type.

Deployment procedures for the FAF game type

The deployment procedure can be a lengthy process because it involves various stages. All the stages are explained below.

Preparation of engine patches

The deployment of engine patches to the release branch is a manual process. This is intentional from a security perspective - it provides a second pair of eyes from a server administrator who is usually not directly related to the game team.

• (1) Make sure that any open changes that you want to include are merged to the master branch of the Binary patches repository.
• (2) Update the executable of the FAF Develop and FAF Beta Balance game types using the Upload workflow.

The workflow requires an approval of another maintainer. Once approved, wait for the workflow to finish.

• (3) Verify the executable on the FAF Develop game type.
• (4) Ask a server administrator to prepare the executable to be updated upon the next game release. This practically involves a copy operation where the server administrator verifies the executable of FAF Develop and copies it to a different location.

You can continue the deployment steps, but you can not finalize it until the server administrator got back to you that it is set. This may take an arbitrary amount of time so make sure this is done at least a week in advance.

Preparation of Lua changes

Most of the preparation steps are automated to reduce the likelihood of errors.

• (1) Push everything that you want to release from develop to the staging/faf branch.
• (2) Generate the necessary file changes and a changelog file using the Prepare release workflow. Add the correct date of the release.
• (3) Once the workflow is completed, navigate to the pull request that has been created.

• (4) Review the changelog and update the following:

• • (4.1) Add an introduction at the top of the changelog.
• • (4.2) Add the contributors at the bottom.
• • (4.3) If it is not one of the quarterly patches, change the title from Game patch to Hotfix
• (5) Commit these changes to the changelog branch.
• (6) Allow some time for the other maintainers to review the changelog.

At this point you need to wait until the changelog branch is merged.

• (7) Create a release on GitHub that targets the develop branch.
• • (7.1) Set the tag with the game version.
• • (7.2) Match the format of the title with that of previous releases.
• • (7.3) Paste a link to our changelog website.
• • (7.4) Create the release.

This step is not technically necessary for the deployment, but it keeps the information on github in sync with our website.

Deployment - final steps

Update the staging/faf branch once more to include the committed changelog branch.

Use the Deploy to FAF Workflow to perform the deployment.

The workflow requires an approval of another maintainer. Once approved, wait for the workflow to finish. You can then review the status of the deployment by the server in the production environment. Once that returns green the deployment succeeded and you can inform the community of the deployment. Congratulations!

Deployment procedures for the development game types

This section applies to both the FAF Beta Balance and the FAF Develop game types. The usual flow is to:

• develop -> force push -> staging/fafbeta -> workflow -> deploy/fafbeta
• develop -> force push -> staging/fafdevelop -> workflow -> deploy/fafdevelop

You can also choose to force push another branch onto the staging area. This allows you to deploy a different branch than develop. This is useful to test experimental changes, without polluting develop and without changing the pull request status.

Deployment workflows

Some facets of deployment are automated to make development easier.

Staging

There are two workflows for staging changes:

• Stage FAF Beta Balance game type
• Stage FAF Develop game type

Relevant branches for the respective game types:

• FAF: staging/faf
• FAF Beta Balance: staging/fafbeta
• FAF Develop: staging/fafdevelop

Staging branches make it easier to:

• Test individual changes or commits: Force push the develop branch to a staging branch, proceed to cherry-pick the desired changes and then trigger the deployment workflow.
• Test experimental changes from a pull request: Force push the branch to a staging branch, then trigger the deployment workflow.

Staging branches are periodically updated automatically to keep them aligned with ongoing development. You can review the schedule by evaluating the cron expression in the workflow files.

Deployment

There are three workflows for deployment:

• Deploy FAF game type
• Deploy FAF Beta Balance game type
• Deploy FAF Develop game type

Each deployment workflow picks up commits from a staging branch, post-processes them, and force pushes them to a branch that triggers deployment. Relevant branches:

• FAF: staging/faf -> deploy/faf
• FAF Beta Balance: staging/fafbeta -> staging/fafbeta
• FAF Develop: staging/fafdevelop -> staging/fafdevelop

The deployment workflows for FAF Beta Balance and FAF Develop are triggered periodically. You can review the schedule by evaluating the cron expression in the workflow files.

The FAForever API registers the push to a deployment branch via webhook. The server creates and updates a deployment status. During this process, the server retrieves and processes the relevant game files. If successful, the new game version becomes available within approximately 5 to 10 minutes.

These workflows exist to apply some post processing of blueprints and various Lua modules. Not all of the post processing is implemented yet.

FAQ

The deployment is not working

This could be one of many reasons:

Deployment to production failed.

This means there’s an internal server error. You can not investigate this without access to the server. Reach out to a server administrator to search through the relevant logs for you. This happened once when the deployed commit contained emoticons.

Deployment to production succeeded, but the client is not downloading the latest files.

The server keeps track of the latest game version. If you push changes that have a lower game version then the deployment ‘succeeds’, but it does not actually deploy. This can happen when you push relatively old pull requests to the staging area to deploy. This is common after a release just happened.