Skip to content

Release Process

Jump to bottom
Justin Obara edited this page Feb 26, 2024 · 15 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 bump the version number 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

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

    # Change to your local staging branch
git checkout staging

# Fetch from the GitHub repo; assumes your remote is named upstream.
git fetch upstream

# Ensure there are no changes in your local staging branch that aren't present in the GitHub staging branch
git log staging ^upstream/staging

# Merge your local staging with upstream to make sure they are in sync
git merge upstream/staging

# Merge in the tag (replace the {tag name} with the tag you just created
git merge {tag name}

# 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 upstream staging

    NOTE: An alternative would be to create a PR from dev to staging and production in GitHub and merge the PR.

  2. On GitHub, the staging branch will display the GitHub action for mirroring the staging branch from GitHub to the hosted GitLab instance.

  3. Once the GitLab instance has been updated, it will trigger a CI/CD job to deploy to Kubernetes. (requires access to see).

  4. Once deployed to Kubernetes it will take about several minutes for the pods to be redeployed. (requires access to see).

  5. If the staging site deployment is working properly, repeat the above steps for the production branch as needed.

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.

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@example.com', '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