VOOZH about

URL: https://deepwiki.com/auth0/wordpress/5.5-updates-and-versioning

⇱ Updates and Versioning | auth0/wordpress | DeepWiki

Loading...
Loading...
Menu

Updates and Versioning

Purpose and Scope

This document explains the plugin's update and versioning system, including version numbering conventions, the WordPress update integration mechanism, version storage locations, and the release process. It covers how the plugin tracks its version, how updates are checked and distributed, and how releases are packaged and signed for security.

For detailed information about the build and packaging process, see Build and Packaging. For information about configuring the plugin, see Configuration Options.

Version Numbering Scheme

The Auth0 WordPress plugin follows Semantic Versioning 2.0.0 (SemVer) with the format MAJOR.MINOR.PATCH:

  • MAJOR: Incremented for incompatible API changes or major architectural changes (e.g., 4.x.x → 5.0.0)
  • MINOR: Incremented for backwards-compatible functionality additions (e.g., 5.0.0 → 5.1.0)
  • PATCH: Incremented for backwards-compatible bug fixes and security patches (e.g., 5.0.0 → 5.0.1)

Version numbers may include optional pre-release identifiers following a hyphen (e.g., 5.0.0-beta.1), though production releases use stable version numbers only.

The current version as of this documentation is 5.5.0, which includes security fixes as documented in the changelog.

Sources: CHANGELOG.md1-72 build.sh13-29

Version Storage Locations

The plugin version is stored in multiple locations throughout the codebase to ensure consistency across different systems and contexts.

Version Storage Diagram



Sources: wpAuth0.php1-90 .version1-2 build.sh1-62


Version Locations Table











































LocationPurposeFormatExample
wpAuth0.php7WordPress plugin header for plugin discoveryVersion: X.Y.ZVersion: 5.5.0
wpAuth0.php26PHP constant for runtime version checksdefine('WP_AUTH0_VERSION', 'X.Y.Z')define('WP_AUTH0_VERSION', '5.5.0')
.version1Build system version trackingX.Y.Z5.4.0
CHANGELOG.md3Release history and notes## <FileRef file-url="https://github.com/auth0/wordpress/blob/be493df4/X.Y.Z" undefined file-path="X.Y.Z">Hii</FileRef> (YYYY-MM-DD)## <FileRef file-url="https://github.com/auth0/wordpress/blob/be493df4/5.5.0" undefined file-path="5.5.0">Hii</FileRef> (2025-12-16)
updates.json2-4Update manifest for distributionJSON object with version keys"5.3.0": { "download": "..." }


Sources: wpAuth0.php1-90 .version1-2 CHANGELOG.md1-72 updates.json1-6




Updates Action Class


The Updates action class integrates with WordPress's plugin update system through transient filters. This class is responsible for intercepting update checks and potentially injecting custom update information.


Updates Class Structure




Sources: src/Actions/Updates.php1-39


Registry Configuration


The Updates class uses the registry property to map WordPress filter hooks to handler methods:




These filters intercept WordPress's plugin update check mechanism when it queries for available updates. The filters fire when WordPress:


    

  • Checks for updates via the WordPress admin dashboard
    • 

  • Performs automatic background update checks
    • 

  • Manually triggers update checks
    • 



Sources: src/Actions/Updates.php12-15


doUpdateCheck Method


The doUpdateCheck() method is called when WordPress checks for plugin updates. The current implementation is a validation handler that ensures the $plugins object has a valid structure:




The method:


    

  1. Validates that $plugins is an object
    2. 

  2. Ensures the response property exists and is an array
    3. 

  3. Returns the (potentially modified) $plugins object
    4. 



The commented-out code at src/Actions/Updates.php29-34 shows the structure for injecting custom update information, but this functionality is not currently active. When implemented, it would populate the response with update metadata including:


    

  • Plugin slug
    • 

  • New version number
    • 

  • Information URL
    • 

  • Download package URL
    • 



Sources: src/Actions/Updates.php17-37




Updates Manifest


The updates.json file serves as a version manifest that tracks available plugin versions and their download locations.


Manifest Structure




Each version entry maps a version number to an object containing:


    

  • download: The filename of the distribution package for that version
    • 



This manifest file is referenced by the update system to determine available versions and their download packages. In a production deployment, this file would be hosted at a known URL and queried by the WordPress update checker.


Sources: updates.json1-6




WordPress Update Integration Flow


The following diagram illustrates how the plugin integrates with WordPress's native update checking system:




Sources: src/Actions/Updates.php1-39


Transient Hooks


The plugin registers two filters to intercept update checks:






















HookContextPurpose
site_transient_update_pluginsSite-wide transient (multisite main site)Intercepts network-wide update checks
transient_update_pluginsSingle site transientIntercepts single-site update checks


Both hooks call the same doUpdateCheck() method, ensuring consistent behavior across single-site and multisite WordPress installations.


Sources: src/Actions/Updates.php12-15




Changelog Structure


The CHANGELOG.md file maintains a comprehensive history of all plugin releases using a standardized format.


Changelog Format


Each release entry follows this structure:




Changelog Categories


Changes are organized under the following headings:



































CategoryUsage
### AddedNew features and capabilities
### UpdatedChanges to existing functionality
### FixedBug fixes and security patches
### ChangedBreaking changes or significant modifications
### DeprecatedFeatures marked for future removal
### RemovedDeleted functionality


Recent Release Examples


Security Release (5.5.0):




Feature Release (5.2.0):




Major Version Release (5.0.0):
The v5.0.0 release includes a comprehensive description of major changes, including:


    

  • WordPress 6 and PHP 8 support
    • 

  • Auth0-PHP SDK integration
    • 

  • Background sync functionality
    • 

  • Flexible identifier support
    • 

  • Enhanced session pairing
    • 



Sources: CHANGELOG.md1-72




Digital Signatures


Distribution packages are digitally signed to ensure authenticity and integrity. The signing process uses OpenSSL with SHA-256 hashing.


Signing Process




Sources: build.sh60-61


Signature Generation


The build script generates a binary signature using the following command:




This creates a .sig file alongside the distribution ZIP archive. The signature can be verified using the corresponding public key to ensure:


    

  • The package has not been tampered with
    • 

  • The package was created by Auth0 (authenticity)
    • 

  • The package integrity is intact
    • 



The private signing key is excluded from version control via .gitignore19


Sources: build.sh60-61 .gitignore19




Release Process Overview


The release process combines version management, build automation, and distribution packaging.


Release Workflow




Sources: build.sh1-62 CHANGELOG.md1-72 updates.json1-6


Build Script Version Validation


The build script includes semantic version validation to ensure version numbers follow the correct format:




This validation ensures that only properly formatted version numbers are used in builds, preventing distribution of incorrectly versioned packages.


Sources: build.sh13-29


Ship Configuration


The .shiprc file configures the ship release tool to manage version updates across multiple files:




This configuration specifies that version numbers should be updated in wpAuth0.php and .version when performing releases, with no version prefix required.


Sources: .shiprc1-8




Version Constant Usage


The WP_AUTH0_VERSION constant defined in wpAuth0.php26 provides runtime access to the plugin version for:


    

  • Telemetry: Reporting the plugin version to Auth0 services
    • 

  • Cache Busting: Versioning static assets to force browser updates
    • 

  • Compatibility Checks: Verifying minimum version requirements
    • 

  • Debug Information: Including version in support logs and error reports
    • 



The constant is globally accessible throughout the WordPress environment once the plugin is loaded.


Sources: wpAuth0.php26




Summary


The Auth0 WordPress plugin implements a comprehensive versioning and update system:


    

  1. Semantic Versioning: Follows SemVer 2.0.0 for predictable version numbering
    2. 

  2. Multiple Version Sources: Maintains version information in plugin headers, constants, and build files
    3. 

  3. WordPress Integration: Hooks into WordPress transient system for update checks
    4. 

  4. Update Manifest: Uses updates.json to track available versions
    5. 

  5. Digital Signatures: Signs distribution packages for security verification
    6. 

  6. Automated Build: Provides build script with version validation and packaging
    7. 

  7. Comprehensive Changelog: Documents all changes in structured format
    8. 



The system is designed to integrate seamlessly with WordPress's native update mechanism while providing additional security through digital signatures and standardized version management across the codebase.


Sources: wpAuth0.php1-90 src/Actions/Updates.php1-39 build.sh1-62 CHANGELOG.md1-72 updates.json1-6