Update Process

This document describes the recommended process for updating the ADP Car Market Hub plugin on a production WordPress site. Following a structured update process reduces the risk of data loss, configuration changes, or frontend regressions.

When to use this document

Read this document whenever a new version of the plugin is available and you need to apply it to a live site. Also read it before any scheduled WordPress core update that may affect plugin compatibility.

Overview

Plugin updates may include bug fixes, security patches, new features, or database schema changes. The plugin handles database schema migrations automatically on activation and on plugins_loaded, but a staging test before production deployment is strongly recommended for significant version changes.

The general process is: review the changelog → take a backup → test on staging → apply on production → verify operation.

Requirements

• Administrator access to the WordPress admin on both the staging environment and the production environment.
• A recent full backup of the production database and uploads directory (see Backup and Restore).
• A staging environment that mirrors the production site. If no staging environment exists, take a complete backup before updating and be prepared to roll back.
• The manage_as24_imports capability on the account performing the update.

Step-by-step instructions

Step 1: Review the release notes

1. Read the release notes for the new version (see Release Notes).
2. Identify any breaking changes, database migrations, or configuration steps listed in the release notes.
3. Note any new PHP version or WordPress version requirements. The plugin requires PHP 8.1 or later and WordPress 6.2 or later as of version 1.0.0. Check the plugin file header or readme.txt for the current declared requirements.

Step 2: Take a complete backup

1. Back up the production database and the wp-content/uploads/ directory before any changes are made.
2. Note the current plugin version so you can roll back to it if needed.
3. Store the backup in a location that is accessible even if the WordPress admin becomes unavailable (for example, a hosting-level backup or a local download).

Step 3: Test the update on staging

1. Apply the new plugin version to the staging site.
2. If the staging site does not reflect the current production state, restore a recent production backup to staging before applying the update.
3. After updating on staging, verify the following: - The plugin admin pages load without PHP errors or white screens. - The Health tab shows no new critical issues. - The API connection status is Connected in the System & Help tab. - A manual import completes successfully (use the Trigger import now button in Automation). - Imported vehicle listings display correctly on the frontend archive and single-vehicle pages. - The lead contact form submits successfully and delivers a notification email. - Analytics tracking events are recorded (if analytics is enabled).
4. If any issues are found on staging, do not proceed to production. Report the issue and wait for a fix or guidance.

Step 4: Apply the update to production

Option A: Update via WordPress admin

1. Log in to the production WordPress admin.
2. Navigate to Dashboard → Updates (or Plugins → Installed Plugins).
3. Locate ADP Car Market Hub in the update list and click Update.
4. WordPress will deactivate the plugin, replace the plugin files, and reactivate it. The plugin's activation hook runs schema and option migrations automatically.

Option B: Manual file update

1. Put the site into maintenance mode if your workflow requires it.
2. Download the new plugin version package.
3. Via SFTP or your hosting file manager, replace the contents of wp-content/plugins/adp-car-market-hub/ with the new version files.
4. The plugin's plugins_loaded hook will trigger schema migrations when the next WordPress request is served.

Step 5: Verify the production update

1. Open ADP Car Market Hub → System & Help and confirm the API connection status is Connected.
2. Check the Dashboard tab and confirm that vehicle counts and last-run information are present.
3. Open the Logs tab and confirm there are no new errors related to the update.
4. Navigate to the frontend vehicle archive page and confirm that listings load correctly.
5. If the plugin version number is displayed anywhere in the admin (for example, the Health or Support tab), confirm it shows the new version.
6. Trigger a manual import from the Import & Limits tab and confirm it completes without errors.

Step 6: Monitor for 24–48 hours

1. After the production update, perform the standard daily checks (see Daily Operation) for the next one to two days.
2. Watch for new errors in the Logs tab.
3. Confirm that scheduled imports continue to run on time.

Configuration reference

Operational notes

• The plugin uses plugins_loaded and admin_init hooks to check and apply database schema migrations. Schema upgrades run automatically and do not require manual SQL execution.
• The plugin registers a custom capability (manage_as24_imports) during activation. If this capability is missing after an update, deactivate and reactivate the plugin to trigger the capability registration.
• The plugin stores a database version in the WordPress options table (as24ci_db_version). The plugin reads this value and applies any pending migrations when it detects a version mismatch.
• Custom template overrides stored outside the plugin directory (for example, in a child theme) are not affected by plugin updates. However, if the update changes the template structure, your custom templates may need to be updated to match.
• The image queue, import lock transients, and cached access token are not affected by plugin updates. In-progress import runs should complete normally.

Rolling back

If the production update causes problems and a rollback is required:

1. Restore the database backup taken in Step 2.
2. Restore the previous plugin files from the backup or by downloading the previous version.
3. The previous plugin version will detect the restored database state and the data will be consistent.
4. Investigate the cause of the failure before attempting the update again.

Troubleshooting

Related documents

• Backup and Restore
• Monthly Maintenance
• Logging and Monitoring