Skip to content

Release Process

Jump to bottom
Justin Obara edited this page Nov 6, 2024 · 16 revisions

Release Process

See also: TAE Release Process video.

Code Freeze and QA

Announce a code freeze and start QA process. At this time, no new code should be merged other that what is needed to address blockers identified during QA and things needed for the release process itself. QA can be performed against the dev site.

Once QA has completed and all blockers for the release addressed, the release process can continue.

Check Milestone for Current Release

Make sure that all of the issues for the current milestone have been completed. If there are any open issues, either complete them or move to another milestone as needed. Once all of the issues for the milestone have been completed, close the milestone.

Sync Localization Files from CrowdIn

Make sure that all translations have been synced to the repository.

  1. Go CrowdIn (requires an account with access to the TAE project)
  2. Go to Integrations > GitHub
  3. Click "Sync Now" to force sync any changes from CrowdIn to the GitHub repository

If there are any changes, in a few minutes a branch with the changes will be pushed to the repo and an PR generated against the dev branch with the changes. This will need to be merged into the GitHub repo.

Tag and Release

This project uses Release Please to automate the release and tagging process. As changes are merged into the dev branch, Release Please maintains a PR for the upcoming release. Release Please bumps the version number in composer.json and will take care of generating the release notes, the GitHub release, and Git tag. All of those steps will be completed when the release PR is merged into the dev branch.

The version number uses SemVer and will automatically be bumped based on the commit prefixes. See: "How should I write my commits" for more information.

NOTE: The Publish Release GitHub action can be triggered manually from the Actions page. This may be useful if you need to modify a release notes (see: "How can I fix release notes?").

Merge to Staging and Production

After a release has been published, it will automatically trigger the release tag to be merged into the staging branch.

For releasing to production, or if the release isn't automatically merged into staging, you can trigger the "Merge Release" workflow manually.

  1. Go to the Actions tab in the GitHub Repository
  2. Select the Merge Release workflow from the left navigation.
  3. Expand the "Run workflow" drop down
  4. Set the branch (staging or production) to merge into and the release tag to merge (you can find this from the release page)
  5. Activate the "Run workflow" button

After the release has been merged:

  1. On GitHub, the respective branch will display the GitHub action for mirroring the staging branch from GitHub to the hosted GitLab instance.
  2. Once the GitLab instance has been updated, it will trigger a CI/CD job to deploy to Kubernetes. (requires access to see).
  3. Once deployed to Kubernetes it will take about several minutes for the pods to be redeployed. (requires access to see).

Typically you'll release to staging first and test out the changes before releasing to production.

NOTE: Special access is required to see the status of the GitLab pipeline and Kubernetes deployment.

NOTE: If the deployment fails, may need to check the Kubernetes deployment and/or talk to CoLab (the site host) to investigate. Some deployment failures may be related to dependency changes, file permissions, caching, or database.

Manually merging releases

If the "Merge Release" workflow does not work, or you prefer to manually release, you can use git commands in a terminal to perform the merging locally and then push up to GitHub.

Locally merge the tagged version into the branch (staging or production) and push up to GitHub; ensure your local branches are clean and up-to-date with the GitHub repo before merging.

  1. Checkout out the branch locally

    git checkout {branch name}

  2. Fetch from the project's GitHub repo remote. Likely origin or upstream

    git fetch {remote name}

  3. Ensure there are no changes in your local branch that aren't present in the project's GitHub branch

    git log {branch name} ^{remote name}/{branch name}

  4. Merge your local branch with the project's GitHub branch to make sure they are in sync

    git merge {remote name}/{branch name}

  5. Merge in the release tag

    git merge {tag name}

  6. Push the merged changes back up to GitHub. If you have a GitHub fork you can push there first to verify the changes.

    git push {remote name} {branch name}

Run migrations and seeders

Update database tables

NOTE: This is the typical migrations that will be run on staging and production deployments. These should be done automatically as part of the deploy, but can be run manually if needed.

  1. Login into Kubernetes cloud dashboard
  2. Open one of the application pods
  3. Exec into the pod to get access to a shell
  4. Put the site into maintenance mode php artisan down
  5. Update the migrations, php artisan migrate
  6. Restore the staging site from maintenance mode php artisan up

Wipe/replace and re-seed database

NOTE: This is only required if the dev or staging database needs to be wiped, and/or updated/replaced by data from seeders

This is typically only going to be needed for the dev or staging deployment.

  1. Login into Kubernetes cloud dashboard for staging
  2. Open one of the application pods
  3. Exec into the pod to get access to a shell
  4. Put the site into maintenance mode php artisan down
  5. Update the migrations, clear the database, and run the production seeder php artisan migrate:fresh
    1. for the dev site, can use the DevSeeder. php artisan migrate:fresh --seeder DevSeeder
  6. Restore the site from maintenance mode php artisan up

Re-seed a single database table

NOTE: This is not a typical action but may be needed if there are a large number of changes to a relatively static table. It should be avoided where possible and cannot be used if anything depends on the IDs.

  1. Backup database as needed
    1. Log into PhpMyAdmin
    2. Go to the database
    3. Go to the Export tab
    4. Export the database as needed.
  2. Login into Kubernetes cloud dashboard for the deployment
  3. Open one of the application pods
  4. Exec into the pod to get access to a shell
  5. Put the site into maintenance mode php artisan down
  6. Truncate the table to be re-seeded
    1. Launch tinker to run Laravel application commands to truncate the table; php artisan tinker
    2. Run {ModelName}::truncate(); where {ModelName} should be replaced by the name of the model for whose table needs to be truncated. For example to truncate the interpretations table run Interpretation::truncate();
    3. Exit tinker; run exit
  7. Re-seed the database table
    1. Run php artisan db:seed --class={SeederName} where {SeederName} is replaced by the name of the Seeder to run. This seeder must be specific to the table that needs to be re-seeded and not one that affects any other table.
  8. Verify the database is correct. If it isn't, restore the database from the backup.
  9. Restore the site from maintenance mode php artisan up

Create Necessary Admin Accounts

For the production site this should not be needed after the initial "production" release unless new accounts are required. For the staging, this is only needed if the previous step was performed and the database wiped.

  1. Login into Kubernetes cloud dashboard for staging
  2. Open one of the application pods
  3. Exec into the pod to get access to a shell
  4. Launch tinker to run Laravel application commands to create the account(s); php artisan tinker
  5. Create the account for example: User::factory()->create(['email' => '[email protected]', 'name' => 'User Name', 'context' => 'administrator']). This user will need to reset their password immediately by using the forgot password flow from the staging site.

Testing

After the site is updated, run through the release test plans (see below) and verify that paths through the system are functioning as expected. Any blocker issues must be addressed immediately.

Lift Code Freeze

Now that the release has been completed successfully, the repository can again receives merges of new code changes.

Clone this wiki locally