> ## Documentation Index
> Fetch the complete documentation index at: https://engineering.trewknowledge.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploying Major updates

> Best practices for safely deploying major updates

Deploying plugin and WordPress updates requires careful planning and coordination to minimize downtime and prevent potential issues. This guide outlines the recommended process for managing these updates across your environments.

## Updating Plugins

As a developer, you will be responsible for the following steps:

<Steps>
  <Step title="Ensure the Local, Production and Preprod/Staging environments are running the same version of WordPress and PHP">
    <Warning>
      This is a critical step to ensure that the updates are compatible with the target version of WordPress and PHP.

      If your local WordPress version is higher than the target version, you must downgrade to the target version before beginning the update process.
    </Warning>
  </Step>

  <Step title="Create a new feature branch from the main/master branch" />

  <Step title="Update plugins locally" />

  <Step title="Review/Test the updates on lower environments">
    1. Test on `develop`
    2. Test on `preprod/staging`

    <Warning>Testing in preprod/staging is mandatory.</Warning>

    <Tip>
      VIP provides a [basic testing checklist](https://docs.wpvip.com/launch-a-site/testing-your-site/).
    </Tip>
  </Step>

  <Step title="Request a QA Review" />

  <Step title="Request a deployment window from your Technical Lead" />
</Steps>

## Updating WordPress

As a developer, you will be responsible for the following steps:

<Steps>
  <Step title="Update WordPress locally" />

  <Step title="Update lower environments to the target version of WordPress" />

  <Step title="Review/Test the updates on lower environments">
    1. Test on `develop`
    2. Test on `preprod/staging`

    <Warning>Testing in preprod/staging is mandatory.</Warning>

    <Tip>
      VIP provides a [basic testing checklist](https://docs.wpvip.com/launch-a-site/testing-your-site/).
    </Tip>
  </Step>

  <Step title="Request a QA Review" />

  <Step title="Request a deployment window from your Technical Lead" />
</Steps>

## The Deployment

<Warning>
  If we cannot complete any of the steps below, we will need to re-evaluate the deployment plan.
</Warning>

As a Technical Lead, you will be responsible for the following steps:

<Steps>
  <Step title="Confirm with the QA analyst that the update is ready to be deployed" />

  <Step title="Verify you have all the necessary access to deploy and rollback the update" />

  <Step title="Create a Launch Runbook">
    1. Outline the steps to be taken **before** the deployment.
    2. Outline the steps to be taken **during** the deployment.
    3. Include the steps to be taken **after** the deployment.
    4. Include the steps to be taken if the deployment **fails**.
    5. Include the steps to be taken if the deployment is **successful**.
    6. Include a rollback plan for major issues, such as fatal errors.

    <Tip>
      Rolling back from the VIP environment is quicker than waiting for a GitHub deployment.

      [Rollbacks in the VIP Dashboard](https://docs.wpvip.com/code-deployment/rollbacks/)
    </Tip>
  </Step>

  <Step title="Coordinate a deployment window">
    * Coordinate a time when the developer, the QA analyst, and the client will all be available to deploy the update.
    * The client doesn't necessarily need to be present, but they should be aware of the update and the potential impact on the site.
    * The window should be during off-peak hours and not during a <Tooltip tip="Black Friday, Cyber Monday, etc...">high-traffic period</Tooltip>.
    * Send the meeting invite and bridge to the team and client.
  </Step>

  <Step title="Double check the versions match">
    If we update plugins, the WordPress versions between staging/preprod and production must match.

    If we are updating WordPress, ensure we are updating to the same version we tested.
  </Step>

  <Step title="Create database and file system backups">
    If the site is hosted with WordPress VIP, we need to trigger a manual database backup. The filesystem mirrors what is currently in the GitHub repository
    If the site is hosted with another provider, like WP Engine, we need to create a restore point. Instructions may vary by host.

    <Info>
      [WordPress VIP: Generate a fresh database backup](https://docs.wpvip.com/databases/backups/generate-a-fresh-database-backup/)
      [WP Engine: Create a restore point](https://docs.wpenginepowered.com/wp-engine/wp-engine-hosting/wp-engine-hosting-features/restore-points/)
    </Info>
  </Step>

  <Step title="Deploy" />

  <Step title="Test thoroughly">
    * The QA analyst should also test everything at the same time.
    * If we have automated testing configured, we should run it.
    * Check the logs for any errors or warnings.

    <Tip>
      You can use the VIP dashboard to [check the logs](https://docs.wpvip.com/logs/runtime-logs/).
    </Tip>
  </Step>

  <Step title="Notify the client and broader team that the update is complete">
    Make sure QA is finished and satisfied.
  </Step>
</Steps>

## Post-Deployment

1. Monitor:
   * Site performance
   * Error rates
   * User experience
2. Document completed updates

## Best Practices

* **Never** push updates directly to production
* Always test in lower environments first
* Maintain version parity across environments
* Schedule updates during off-peak hours and not during a <Tooltip tip="Black Friday, Cyber Monday, etc...">high-traffic period</Tooltip>
* Keep comprehensive deployment logs
* Use a staging environment that mirrors production
* Implement automated testing where possible
* Have a rollback plan ready