README.md
64 lines
| 1 | # SiteOrigin GitHub Updater |
| 2 | |
| 3 | SiteOrigin GitHub Updater enables WordPress to obtain plugin updates directly from GitHub Releases, rather than the WordPress.org repository. The implementation is optimized for SiteOrigin-maintained plugins, but the source code is public and may be adapted for other projects. |
| 4 | |
| 5 | ## What It Does |
| 6 | |
| 7 | * Queries the GitHub Releases API for the most recent published release (non-draft, non-prerelease). |
| 8 | * Compares the release tag to the `Version` header of the installed plugin. |
| 9 | * When a higher version is detected, WordPress presents a standard update notice and installs the ZIP asset linked to that release. |
| 10 | * For WordPress versions earlier than 5.8, or when an `Update URI` header is missing, the updater can fall back to a branch-based check. |
| 11 | |
| 12 | ## Integrating the Updater |
| 13 | |
| 14 | 1. **Add the submodule** |
| 15 | |
| 16 | ``` |
| 17 | cd path/to/plugin |
| 18 | git submodule add https://github.com/siteorigin/github-updater.git github-updater |
| 19 | git submodule update --init --recursive |
| 20 | ``` |
| 21 | |
| 22 | 2. **Load and initialize** |
| 23 | |
| 24 | ```php |
| 25 | // Include the updater library. |
| 26 | require_once plugin_dir_path( __FILE__ ) . 'github-updater/updater.php'; |
| 27 | |
| 28 | // Instantiate the updater. |
| 29 | new SiteOrigin_Updater( |
| 30 | __FILE__, // Path to this main plugin file. |
| 31 | 'your-plugin-slug', // Plugin directory name (e.g., 'my-plugin'). |
| 32 | 'your-github-owner/your-repository-name', // GitHub owner and repository name (e.g., 'my-username/my-plugin'). |
| 33 | // Optional fourth argument: branch for legacy updates (default 'master'). |
| 34 | ); |
| 35 | ``` |
| 36 | * Replace `'your-plugin-slug'` with your plugin's directory name. |
| 37 | * Replace `'your-github-owner/your-repository-name'` with the GitHub owner (username or organization) followed by a slash and then the repository name. For example, if your repository URL is `https://github.com/my-username/my-cool-plugin`, this argument would be `'my-username/my-cool-plugin'`. |
| 38 | * The fourth parameter for the branch is optional and is used for the legacy update system (defaults to 'master'). |
| 39 | |
| 40 | 3. **Define the `Update URI` header** |
| 41 | |
| 42 | ```php |
| 43 | /* |
| 44 | * Plugin Name: Example Plugin |
| 45 | * Version: 1.2.3 |
| 46 | * Update URI: https://github.com/your-github-owner/your-repository-name |
| 47 | */ |
| 48 | ``` |
| 49 | |
| 50 | ## Releasing a New Version |
| 51 | |
| 52 | 1. Increment the `Version` header. |
| 53 | 2. Commit and push all changes. |
| 54 | 3. On GitHub, create a release whose tag matches the new version (for example, `1.2.4` or `v1.2.4`) and attach the installable ZIP file. |
| 55 | 4. WordPress installations will detect and apply the update during their next routine check. |
| 56 | |
| 57 | ## Legacy Update Mechanism |
| 58 | |
| 59 | For environments running WordPress < 5.8 or lacking a valid `Update URI`, the updater retrieves the main plugin file from a designated branch (default `master`), compares version numbers, and supplies the update directly from that branch. |
| 60 | |
| 61 | ## Licence |
| 62 | |
| 63 | GPL-3.0. Refer to the included `LICENSE` file for details. |
| 64 |