Deployment
In this repository we can deploy to three different environments:
deploy/faf
- theFAF
game type. This is the default release branch and is used by matchmakerdeploy/fafbeta
- theFAF Beta Balance
game type. This branch only contains balance changes and bug fixes.deploy/fafdevelop
- theFAF 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.
Deployment 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
andFAF 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.
Deployment of Lua
- (0) Checkout on the develop branch and pull in the latest version. Make sure that there are no other open changes.
- (1) Create a new branch that originates from develop. We’ll refer to this branch as the
changelog branch
. - (2) Generate the changelog using the Changelog generation workflow with the develop branch as target.
- (3) Once the workflow is completed, navigate to the summary section and download the artifact that is created by the workflow.
- (4) Save the generated changelog to a new file in the format
yyyy-mm-dd-game-version.md
indocs/_posts
. As an example for a file name:2024-08-03-3811.md
. - (5) Verify and update the content of the changelog is complete.
-
- (5.1) Add the front matter (what is in between
---
) at the top, for example:
- (5.1) Add the front matter (what is in between
---
layout: post
title: Game version 3811
permalink: changelog/3811
---
-
- (5.2) Add an introduction at the top of the changelog.
-
- (5.3) Add the contributors at the bottom.
- (6) commit this file to the changelog branch.
- (7) Delete the current snippets.
- (8) Update the game version in mod_info.lua and version.lua.
- (9) Update the latest version in changelogData.lua and add a short version of the patchnotes there. Add an explanation that players can use the in-game button to github to read the detailed changes.
- (10) Push the changes to GitHub. Create a pull request on GitHub to allow other maintainers to review the changelog. Make sure the pull request points to develop.
At this point you need to wait until the changelog branch
is merged.
- (11) Push everything that you want to release from develop to the staging/faf branch.
Deployment - final steps
- (1) Create a release on GitHub that targets the [develop(https://github.com/FAForever/fa/tree/develop) branch.
-
- (1.1) Set the tag with the game version.
-
- (1.2) Match the format of the title with that of previous releases.
-
- (1.3) Copy and paste the changelog into the description. Make sure to remove the title as a release has its own title.
-
- (1.4) Create the release.
- (2) 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:
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:
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.