3SD staff handbook

Appearance

Upgrade process ​

Below are the stages of the upgrade process. Each client is likely to have different steps in this process so it should be customised per client.

Preparation ​

CiviCRM ​

  • Check for changes to core overrides with com.klangsoft.overrides
  • Review message template customisations (if any)
  • Download CiviCRM and localisation files from
  • Delete civicrm folder and replace with latest version
  • Copy l10n folder from localisation files into civicrm folder
  • Upgrade the CiviCRM database docker compose exec -u civicrm app cv updb
  • Re-apply patches to core files (if necessary)
  • Replace the phpcs.xml file in WordPress sites at /src/wordpress/wp-content/plugins/civicrm/civicrm/phpcs.xml - see Coding standards
  • Merge changes into extensions that override core files (if necessary)
  • Merge changes into customised message templates (if necessary)
  • Check for and fix missing indices - see dev/core#4544
    sh
    docker compose exec -u civicrm app cv api System.getmissingindices 
docker compose exec -u civicrm app cv api System.updateindexes
  • Update the wiki as required

CiviCRM extensions ​

  • Apply updates via the UI
  • Re-apply patches to extensions (if required)
  • Merge core changes into overrides (if not done above)

TIP

By default CiviCRM only shows updates for approved extensions that are listed as available for release via the UI. It doesn't show updates for unapproved extensions. See dev/core#3035.

If you add the following line to civicrm.settings.php it will show updates for unapproved extensions but you will still need to check manually for extensions that aren't listed on CiviCRM.org

php
$civicrm_setting['domain']['ext_repo_url'] = 'https://civicrm.org/extdir/ver={ver}|cms={uf}|ready=';

Drupal ​

  • Check for updates docker compose exec -u civicrm app drush ups
  • Update Drupal core docker compose exec -u civicrm app drush up drupal
  • Update modules docker compose exec -u civicrm app drush up [module]

WordPress ​

  • Check for updates docker compose exec -u civicrm app wp core check-update
  • Update WordPress (minor) docker compose exec -u civicrm app wp core update --minor
  • Update WordPress (major) docker compose exec -u civicrm app wp core update
  • Update plugins docker compose exec -u civicrm app wp plugin update --all
  • Update themes docker compose exec -u civicrm app wp theme update --all
  • Update translations - via UI

Docker ​

  • Update PHP version in docker-compose.*.yml to highest supported by CiviCRM
  • Update docker image
    shell
    docker compose pull
docker compose up -d

Reset test branch to master ​

Over time the test branch may diverge from master. There may be MRs that have been deployed to test that haven't been deployed to master. This can cause problems when testing, particularly if there are CiviCRM core overrides that don't match the upgrade branch.

To avoid this it is best to reset the test branch to master so that there is a clean test environment and we are only testing what is in the upgrade.

Resetting the branch means that any code in the test branch will be lost so you may want to compare the two branches (test and master) before doing this to see what the differences are. You can also create a branch (e.g. test-old) so that you don't lose these changes. If needed other MRs can be re-applied to test after the upgrade testing is complete.

The steps in GitLab are:

  • (optional) create a new branch test-old from test
  • delete the test branch
  • create a new test branch from master

You will then need to update the test branch on the test server:

shell
git fetch --all
git checkout master
git branch -D test
git checkout test

Deploy to test ​

  • Sync from prod ./sync
  • Clear caches
    shell
    docker compose exec -u civicrm app wp cache flush
docker compose exec -u civicrm app drush cc all
docker compose exec -u civicrm app cv flush
  • Pre-upgrade steps - e.g. uninstalling extensions/plugins/modules
  • Merge branch into test
  • Update code git pull test
  • Update CiviCRM database docker compose exec -u civicrm app cv updb - best to update CiviCRM before CMS
  • Update WordPress database docker compose exec -u civicrm app wp core update-db
  • Update Drupal database docker compose exec -u civicrm app drush updb
  • Update docker image
    shell
    docker compose pull
docker compose up -d
  • Post-upgrade steps - e.g. installing new extensions/plugins/modules

Deploy to production ​

  • Finalise date with client - preferably in the moring at the start of the week - avoid deployment on a Friday or immediately before holiday
  • Inform client of expected downtime and whether staff/visitors can access the site during the upgrade
  • Take a backup docker compose exec -u civicrm app civicrm-docker-dump
  • Pre-upgrade steps - e.g. uninstalling extensions/plugins/modules
  • Merge branch into master
  • Update code git pull master
  • Update CiviCRM database docker compose exec -u civicrm app cv updb - best to update CiviCRM before CMS
  • Update WordPress database docker compose exec -u civicrm app wp core update-db
  • Update Drupal database docker compose exec -u civicrm app drush updb
  • Update docker image
    shell
    docker compose pull
docker compose up -d
  • Post-upgrade steps - e.g. installing new extensions/plugins/modules

GitLab issue template ​

This checklist can be copied and pasted into the GitLab issue. More details about specific steps are found above.

md
## Release notes

_Put a summary of the key changes here. With links for further information if relevant._

## Versions

CiviCRM is being upgraded from _Old Version_ to _New version_
WordPress is being upgraded from _Old Version_ to _New version_

## Task list

Preparation

- [ ] Inform the client of the planned upgrade and timeline
- [ ] Sync dev instance from production
- [ ] Create a branch in GitLab for the upgrade
- [ ] Read the client wiki for information about any overrides or specific upgrade steps
- [ ] Read the release notes
  - [ ] CiviCRM
  - [ ] Version specific upgrade steps
  - [ ] CiviCRM extensions
  - [ ] CMS
  - [ ] CMS plugins/modules

CiviCRM

- [ ] Review core overrides
- [ ] Review message template customisations
- [ ] Upgrade CiviCRM core and localisation files
- [ ] Re-apply patches to core files (if any)
- [ ] Review the CiviCRM extensions in use
  - [ ] remove any that are no longer needed
- [ ] Update CiviCRM extensions
- [ ] Re-apply patches to CiviCRM extensions (if any)
- [ ] Replace `/src/wordpress/wp-content/plugins/civicrm/civicrm/phpcs.xml` (WordPress only)
- [ ] Merge changes to core files into extension overrides
- [ ] Merge core changes into message templates
- [ ] Check for and fix missing indices (if needed)
  ```sh
  docker compose exec -u civicrm app cv api System.getmissingindices 
  docker compose exec -u civicrm app cv api System.updateindexes
  ```
- [ ] Update the client wiki

CMS

- [ ] Update the CMS
- [ ] Re-apply any patches to the CMS (if any)
- [ ] Review the CMS plugins
  - [ ] Remove any that are no longer needed
- [ ] Update CMS plugins
- [ ] Re-apply patches to CMS plugins (if any)
- [ ] Update the documentation about CMS and plugin overrides

Docker

- [ ] Update PHP to highest version supported by CiviCRM
- [ ] Pull latest `civicrm-docker` image

Testing / QA

- [ ] Reset `test` branch to `master`
- [ ] Sync test server from production
- [ ] Pre-upgrade steps - e.g. uninstalling extensions/plugins/modules (if any)
- [ ] Merge MR into `test` branch and deploy to test server
- [ ] Apply database updates
  ```shell
  # CiviCRM and extensions
  docker compose exec -u civicrm app cv updb
  # WordPress and plugins
  docker compose exec -u civicrm app wp core update-db
  # Drupal and modules
  docker compose exec -u civicrm app drush updb
  ```
- [ ] Review update messages and add to issue for client to review (if relevant)
- [ ] Update docker image
  ```shell
  docker compose pull
  docker compose up -d
  ```
- [ ] Check for and fix missing indices (if needed)
  ```sh
  docker compose exec -u civicrm app cv api System.getmissingindices 
  docker compose exec -u civicrm app cv api System.updateindexes
  ```
- [ ] Post-upgrade steps - e.g. installing new extensions/plugins/modules (if any)
- [ ] Run internal QA
- [ ] Fix any issues arising from internal QA
- [ ] Ask client to run QA
- [ ] Fix any issues arising from client QA
- [ ] Perform additional QA and fixing as required

Schedule production upgrade

- [ ] Finalise date with client
- [ ] Inform client of expected downtime and whether staff/visitors can access the site during upgrade

Production upgrade

- [ ] Take backup
- [ ] Pre-upgrade steps - e.g. uninstalling extensions/plugins/modules (if any)
- [ ] Merge MR into `master` branch and deploy to production server
- [ ] Apply database updates
  ```shell
  # CiviCRM and extensions
  docker compose exec -u civicrm app cv updb
  # WordPress and plugins
  docker compose exec -u civicrm app wp core update-db
  # Drupal and modules
  docker compose exec -u civicrm app drush updb
  ```
- [ ] Update docker image
  ```shell
  docker compose pull
  docker compose up -d
  ```
- [ ] Check for and fix missing indices (if needed)
  ```sh
  docker compose exec -u civicrm app cv api System.getmissingindices 
  docker compose exec -u civicrm app cv api System.updateindexes
  ```
- [ ] Post-upgrade steps - e.g. installing new extensions/plugins/modules (if any)
- [ ] Run internal QA
- [ ] Ask client to run QA
- [ ] Update history page in client wiki

Post upgrade

- [ ] Debrief internally and with the client
- [ ] Update the testing checklist as appropriate
- [ ] Review any issues in GitLab marked `~after-upgrade`