From cb44a6ede180064966cc8326af87207598f93da1 Mon Sep 17 00:00:00 2001 From: Tim Wiel Date: Tue, 21 Sep 2021 13:48:25 +1200 Subject: [PATCH 1/7] Adding releases to GitLab API with option for release asset download from either: source OR generic package releases (see https://gitlab.com/gitlab-org/release-cli/-/tree/master/docs/examples/release-assets-as-generic-package/) --- Puc/v4p11/Vcs/GitLabApi.php | 72 +++++++++++++++++++++++++++++++++++-- 1 file changed, 70 insertions(+), 2 deletions(-) diff --git a/Puc/v4p11/Vcs/GitLabApi.php b/Puc/v4p11/Vcs/GitLabApi.php index 8fd3f45..12b3160 100644 --- a/Puc/v4p11/Vcs/GitLabApi.php +++ b/Puc/v4p11/Vcs/GitLabApi.php @@ -28,6 +28,16 @@ if ( !class_exists('Puc_v4p11_Vcs_GitLabApi', false) ): */ protected $accessToken; + /** + * @var bool Whether to download release assets instead of the auto-generated source code archives. + */ + protected $releaseAssetsEnabled = false; + + /** + * @var bool Whether to download release asset package rather than release asset source. + */ + protected $releasePackageEnabled = false; + public function __construct($repositoryUrl, $accessToken = null, $subgroup = null) { //Parse the repository host to support custom hosts. $port = parse_url($repositoryUrl, PHP_URL_PORT); @@ -94,7 +104,49 @@ if ( !class_exists('Puc_v4p11_Vcs_GitLabApi', false) ): * @return Puc_v4p11_Vcs_Reference|null */ public function getLatestRelease() { - return $this->getLatestTag(); + $releases = $this->api('/:id/releases'); + if ( is_wp_error($releases) || empty($releases) || !is_array($releases) ) { + return null; + } + + $release = $releases[0]; + if ( is_wp_error($release) || !is_object($release) || !isset($release->tag_name) ) { + return null; + } + + $reference = new Puc_v4p11_Vcs_Reference(array( + 'name' => $release->tag_name, + 'version' => ltrim($release->tag_name, 'v'), //Remove the "v" prefix from "v1.2.3". + 'downloadUrl' => '', + 'updated' => $release->released_at, + 'apiResponse' => $release, + )); + + if ( $this->isAuthenticationEnabled() ) { + if ( $this->releasePackageEnabled && isset($release->assets, $release->assets->links) ) { + /** + * Use the first asset LINK file generated by a Gitlab Release Pipeline + * + * @link https://gist.github.com/timwiel/9dfd3526c768efad4973254085e065ce + */ + $download_url = $release->assets->links[0]->url; + if ( ! empty( $this->accessToken ) ) { + $download_url = add_query_arg('private_token', $this->accessToken, $download_url); + } + $reference->downloadUrl = $download_url; + } elseif ( $this->releaseAssetsEnabled && isset($release->assets) ) { + /** + * Use the first asset SOURCE file from a Gitlab Release which should be a zip file + */ + $download_url = $release->assets->sources[0]->url; + if ( ! empty( $this->accessToken ) ) { + $download_url = add_query_arg('private_token', $this->accessToken, $download_url); + } + $reference->downloadUrl = $download_url; + } + } + + return $reference; } /** @@ -290,7 +342,12 @@ if ( !class_exists('Puc_v4p11_Vcs_GitLabApi', false) ): // GitLab doesn't handle releases the same as GitHub so just use the latest tag if ( $configBranch === 'master' ) { - $updateSource = $this->getLatestTag(); + //Use the latest release. + $updateSource = $this->getLatestRelease(); + if ( $updateSource === null ) { + //Failing that, use the tag with the highest version number. + $updateSource = $this->getLatestTag(); + } } if ( empty($updateSource) ) { @@ -304,6 +361,17 @@ if ( !class_exists('Puc_v4p11_Vcs_GitLabApi', false) ): parent::setAuthentication($credentials); $this->accessToken = is_string($credentials) ? $credentials : null; } + + public function enableReleaseAssets() { + $this->releaseAssetsEnabled = true; + $this->releasePackageEnabled = false; + } + + public function enableReleasePackage() { + $this->releaseAssetsEnabled = false; + $this->releasePackageEnabled = true; + } + } endif; From 1c63404e98fb4781aa7bbcc36d34e4dadd2d5d38 Mon Sep 17 00:00:00 2001 From: Tim Wiel Date: Tue, 21 Sep 2021 14:00:53 +1200 Subject: [PATCH 2/7] README.md update to reflect Gitlab releases functionality --- README.md | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index ed08b17..63dc69e 100644 --- a/README.md +++ b/README.md @@ -267,10 +267,27 @@ BitBucket doesn't have an equivalent to GitHub's releases, so the process is sli #### How to Release an Update -GitLab doesn't have an equivalent to GitHub's releases, so the process is slightly different. You can use any of the following approaches: - -- **Tags** - +- **GitLab releases** + + Create a new release using the "Releases" feature on Gitlab. Gitlab releases *will only be checked* if the branch is set to master (`$myUpdateChecker->setBranch('master');`) or not specified - releases *will not be checked* if any other branch is specified (`$myUpdateChecker->setBranch('stable-branch-name');`). + + If you want to use Gitlab Releases source code asset, call the `enableReleaseAssets()` + ```php + $myUpdateChecker->getVcsApi()->enableReleaseAssets(); + ``` + OR if you want to use the Gitlab Release generic package instead, call the `enableReleasePackage()` + ```php + $myUpdateChecker->getVcsApi()->enableReleasePackage(); + ``` + + For more information about Gitlab Release generic package refer to the following links: + - [Gitlab Release Documentation](https://docs.gitlab.com/ee/user/project/releases/#create-release-from-gitlab-ci) + - [Gitlab Release Assets as Generic Package Documentation](https://gitlab.com/gitlab-org/release-cli/-/tree/master/docs/examples/release-assets-as-generic-package/) + - [Example .gitlab-ci.yml file using Release Assets as Generic Package for generating a package from the Sensei-LMS wordpress plugin](https://gist.github.com/timwiel/9dfd3526c768efad4973254085e065ce) + + +- **Tags** + To release version 1.2.3, create a new Git tag named `v1.2.3` or `1.2.3`. That's it. PUC doesn't require strict adherence to [SemVer](http://semver.org/). These are all valid tag names: `v1.2.3`, `v1.2-foo`, `1.2.3_rc1-ABC`, `1.2.3.4.5`. However, be warned that it's not smart enough to filter out alpha/beta/RC versions. If that's a problem, you might want to use GitLab branches instead. From 824348c036a50c7aff83d197f0b6e2d108873c11 Mon Sep 17 00:00:00 2001 From: Tim Wiel Date: Wed, 22 Sep 2021 12:11:37 +1200 Subject: [PATCH 3/7] Adding checks for the assets to ensure they are zip files which is what wordpress needs to update --- Puc/v4p11/Vcs/GitLabApi.php | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/Puc/v4p11/Vcs/GitLabApi.php b/Puc/v4p11/Vcs/GitLabApi.php index 12b3160..3b5a0c5 100644 --- a/Puc/v4p11/Vcs/GitLabApi.php +++ b/Puc/v4p11/Vcs/GitLabApi.php @@ -123,22 +123,40 @@ if ( !class_exists('Puc_v4p11_Vcs_GitLabApi', false) ): )); if ( $this->isAuthenticationEnabled() ) { + $download_url = false; if ( $this->releasePackageEnabled && isset($release->assets, $release->assets->links) ) { /** - * Use the first asset LINK file generated by a Gitlab Release Pipeline + * Use the first asset LINK that is a zip format file generated by a Gitlab Release Pipeline * * @link https://gist.github.com/timwiel/9dfd3526c768efad4973254085e065ce */ - $download_url = $release->assets->links[0]->url; + foreach ($release->assets->links as $link) { + if ( 'zip' === substr($link->url, -3) ) { + $download_url = $link->url; + break 1; + } + } + if ( empty( $download_url ) ) { + return null; + } if ( ! empty( $this->accessToken ) ) { $download_url = add_query_arg('private_token', $this->accessToken, $download_url); } + $reference->downloadUrl = $download_url; } elseif ( $this->releaseAssetsEnabled && isset($release->assets) ) { /** - * Use the first asset SOURCE file from a Gitlab Release which should be a zip file + * Use the first asset SOURCE file that is a zip format from a Gitlab Release which should be a zip file */ - $download_url = $release->assets->sources[0]->url; + foreach ($release->assets->sources as $source) { + if ( 'zip' === $source->format ) { + $download_url = $source->url; + break 1; + } + } + if ( empty( $download_url ) ) { + return null; + } if ( ! empty( $this->accessToken ) ) { $download_url = add_query_arg('private_token', $this->accessToken, $download_url); } From e16a46fc726268fb92f2fcb8cf1e7a925f7be76e Mon Sep 17 00:00:00 2001 From: Tim Wiel Date: Wed, 22 Sep 2021 12:53:01 +1200 Subject: [PATCH 4/7] Filtering out "upcoming releases" from the releases available to PUC --- Puc/v4p11/Vcs/GitLabApi.php | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Puc/v4p11/Vcs/GitLabApi.php b/Puc/v4p11/Vcs/GitLabApi.php index 3b5a0c5..36fd465 100644 --- a/Puc/v4p11/Vcs/GitLabApi.php +++ b/Puc/v4p11/Vcs/GitLabApi.php @@ -109,7 +109,11 @@ if ( !class_exists('Puc_v4p11_Vcs_GitLabApi', false) ): return null; } - $release = $releases[0]; + foreach ($releases as $release) { + if ( true !== $release->upcoming_release ) { + break 1; //Break the loop on the first release we find that isn't an upcoming release + } + } if ( is_wp_error($release) || !is_object($release) || !isset($release->tag_name) ) { return null; } From 91d089876fe8650c08c885da36bfab91f8800ab4 Mon Sep 17 00:00:00 2001 From: Tim Wiel Date: Wed, 22 Sep 2021 14:41:02 +1200 Subject: [PATCH 5/7] Ordering the priority of version checks for Gitlab and updating README.md accordingly --- Puc/v4p11/Vcs/GitLabApi.php | 17 +++---- README.md | 89 ++++++++++++++++++++----------------- 2 files changed, 58 insertions(+), 48 deletions(-) diff --git a/Puc/v4p11/Vcs/GitLabApi.php b/Puc/v4p11/Vcs/GitLabApi.php index 36fd465..a4bc46e 100644 --- a/Puc/v4p11/Vcs/GitLabApi.php +++ b/Puc/v4p11/Vcs/GitLabApi.php @@ -362,17 +362,18 @@ if ( !class_exists('Puc_v4p11_Vcs_GitLabApi', false) ): public function chooseReference($configBranch) { $updateSource = null; - // GitLab doesn't handle releases the same as GitHub so just use the latest tag - if ( $configBranch === 'master' ) { - //Use the latest release. + //1. Do releases first irrelevant of branches + if ( $this->releaseAssetsEnabled || $this->releasePackageEnabled ) { $updateSource = $this->getLatestRelease(); - if ( $updateSource === null ) { - //Failing that, use the tag with the highest version number. - $updateSource = $this->getLatestTag(); - } } - if ( empty($updateSource) ) { + //2. Do tag with the highest version number next if branch is master + if ( empty( $updateSource ) === null && $configBranch === 'master' ) { + $updateSource = $this->getLatestTag(); + } + + //3. Do branch if all else fails + if ( empty( $updateSource ) ) { $updateSource = $this->getBranch($configBranch); } diff --git a/README.md b/README.md index 63dc69e..30f17b0 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ From the users' perspective, it works just like with plugins and themes hosted o - [BitBucket Integration](#bitbucket-integration) - [How to Release an Update](#how-to-release-an-update-2) - [GitLab Integration](#gitlab-integration) - - [How to Release an Update](#how-to-release-an-update-3) + - [How to Release an Update](#how-to-release-a-gitlab-update) - [License Management](#license-management) - [Resources](#resources) @@ -227,7 +227,7 @@ BitBucket doesn't have an equivalent to GitHub's releases, so the process is sli ### GitLab Integration 1. Download [the latest release](https://github.com/YahnisElsts/plugin-update-checker/releases/latest) and copy the `plugin-update-checker` directory to your plugin or theme. -2. Add the following code to the main plugin file or `functions.php`: +2. Add the following code to the main plugin file or `functions.php` and define how you want to check for updates from Gitlab (refer to: [Gitlab: How to Release an Update](#how-to-release-a-gitlab-update)): ```php require 'plugin-update-checker/plugin-update-checker.php'; @@ -239,11 +239,8 @@ BitBucket doesn't have an equivalent to GitHub's releases, so the process is sli //Optional: If you're using a private repository, specify the access token like this: $myUpdateChecker->setAuthentication('your-token-here'); - - //Optional: Set the branch that contains the stable release. - $myUpdateChecker->setBranch('stable-branch-name'); ``` - + Alternatively, if you're using a self-hosted GitLab instance, initialize the update checker like this: ```php $myUpdateChecker = new Puc_v4p11_Vcs_PluginUpdateChecker( @@ -260,52 +257,64 @@ BitBucket doesn't have an equivalent to GitHub's releases, so the process is sli __FILE__, 'unique-plugin-or-theme-slug' ); - + ``` - + 3. Plugins only: Add a `readme.txt` file formatted according to the [WordPress.org plugin readme standard](https://wordpress.org/plugins/readme.txt) to your repository. The contents of this file will be shown when the user clicks the "View version 1.2.3 details" link. -#### How to Release an Update +#### How to Release a Gitlab Update +A Gitlab repository can be checked for updates using 4 different options. The default is option 4. -- **GitLab releases** - - Create a new release using the "Releases" feature on Gitlab. Gitlab releases *will only be checked* if the branch is set to master (`$myUpdateChecker->setBranch('master');`) or not specified - releases *will not be checked* if any other branch is specified (`$myUpdateChecker->setBranch('stable-branch-name');`). - - If you want to use Gitlab Releases source code asset, call the `enableReleaseAssets()` - ```php - $myUpdateChecker->getVcsApi()->enableReleaseAssets(); - ``` - OR if you want to use the Gitlab Release generic package instead, call the `enableReleasePackage()` - ```php - $myUpdateChecker->getVcsApi()->enableReleasePackage(); - ``` - - For more information about Gitlab Release generic package refer to the following links: - - [Gitlab Release Documentation](https://docs.gitlab.com/ee/user/project/releases/#create-release-from-gitlab-ci) - - [Gitlab Release Assets as Generic Package Documentation](https://gitlab.com/gitlab-org/release-cli/-/tree/master/docs/examples/release-assets-as-generic-package/) - - [Example .gitlab-ci.yml file using Release Assets as Generic Package for generating a package from the Sensei-LMS wordpress plugin](https://gist.github.com/timwiel/9dfd3526c768efad4973254085e065ce) +1. Update from **GitLab Releases using Generic Packages**: + - Use a Gitlab CI/CD Pipeline to automatically generate your update on release using a Generic Package. The benefit of using Generic Package assets over the Source Code assets as it the code can already be built and production ready. + - Add the following code: + ```php + //Add the following code to your main plugin file or `functions.php` file to check for an new update from releases using generic packages + $myUpdateChecker->getVcsApi()->enableReleasePackage(); + ``` + - PUC will periodically check the release version (i.e. the tag name of the release) and will display a notification if the release is a greater version than the installed version. + - The release tag name should loosely follow [SemVer](http://semver.org/) but these are all valid release names: `v1.2.3`, `v1.2-foo`, `1.2.3_rc1-ABC`, `1.2.3.4.5` However, be warned that it's not smart enough to filter out alpha/beta/RC versions. If that's a problem, you might want to use GitLab branches instead. + - For more information about *Gitlab Release Generic Packages* refer to the following links: + - [Gitlab CI/CD Release Documentation](https://docs.gitlab.com/ee/user/project/releases/#create-release-from-gitlab-ci) + - [Gitlab Release Assets as Generic Package Documentation](https://gitlab.com/gitlab-org/release-cli/-/tree/master/docs/examples/release-assets-as-generic-package/) + - [Example .gitlab-ci.yml file using Release Generic Packages for generating a update package from the Sensei-LMS wordpress plugin](https://gist.github.com/timwiel/9dfd3526c768efad4973254085e065ce) -- **Tags** +2. Update **GitLab Releases using Source Code Assets**: + - Create a new release using the "Releases" feature on Gitlab and PUC will periodically check the release version (based on release tag name) and display a notification if the release version is greater than the installed version. + - Add the following code: + ```php + //Add the following code to your main plugin file or `functions.php` file to check for an new update from releases using release assets + $myUpdateChecker->getVcsApi()->enableReleaseAssets(); + ``` + - The release name should loosely follow [SemVer](http://semver.org/) but these are all valid release names: `v1.2.3`, `v1.2-foo`, `1.2.3_rc1-ABC`, `1.2.3.4.5` However, be warned that it's not smart enough to filter out alpha/beta/RC versions. If that's a problem, you might want to use GitLab branches instead. + - PUC will periodically check the release version (based on release tag name) and display a notification the release has a greater than the installed version. - To release version 1.2.3, create a new Git tag named `v1.2.3` or `1.2.3`. That's it. - - PUC doesn't require strict adherence to [SemVer](http://semver.org/). These are all valid tag names: `v1.2.3`, `v1.2-foo`, `1.2.3_rc1-ABC`, `1.2.3.4.5`. However, be warned that it's not smart enough to filter out alpha/beta/RC versions. If that's a problem, you might want to use GitLab branches instead. -- **Stable branch** - - Point the update checker at a stable, production-ready branch: - ```php - $updateChecker->setBranch('branch-name'); - ``` - PUC will periodically check the `Version` header in the main plugin file or `style.css` and display a notification if it's greater than the installed version. - - Caveat: If you set the branch to `master` (the default), the update checker will look for recent releases and tags first. It'll only use the `master` branch if it doesn't find anything else suitable. +3. Update from any **Gitlab Stable branch** (other than `master`): + - Point the update checker at any stable, production-ready branch and PUC will periodically check the `Version` header in the main plugin file or `style.css` and display a notification if it's greater than the installed version. + - Add the following code: + ```php + //Add the following code to your main plugin file or `functions.php` file to check for an new update from a non-master branch + $myUpdateChecker->setBranch('stable-branch-name'); + ``` + - Caveat: If you set the branch to `master` (the default), the update checker will look for recent releases and tags first. It'll only use the `master` branch if it doesn't find anything else suitable. + + +4. Update from **Tags** on the master branch (default option): + - To release version 1.2.3, create a new Git tag named `v1.2.3` or `1.2.3`. That's it. + - Add the following code: + ```php + //Add the following code to your main plugin file or `functions.php` file to check for an new update from a non-master branch + //OR don't add any of the 4 options to your main plugin file or `functions.php` + $myUpdateChecker->setBranch('master'); + ``` + - PUC doesn't require strict adherence to [SemVer](http://semver.org/). These are all valid tag names: `v1.2.3`, `v1.2-foo`, `1.2.3_rc1-ABC`, `1.2.3.4.5`. However, be warned that it's not smart enough to filter out alpha/beta/RC versions. If that's a problem, you might want to use GitLab branches instead. License Management ------------------ -Currently, the update checker doesn't have any built-in license management features. It only provides some hooks that you can use to, for example, append license keys to update requests (`$updateChecker->addQueryArgFilter()`). If you're looking for ways to manage and verify licenses, please post your feedback in [this issue](https://github.com/YahnisElsts/plugin-update-checker/issues/222). +Currently, the update checker doesn't have any built-in license management features. It only provides some hooks that you can use to, for example, append license keys to update requests (`$updateChecker->addQueryArgFilter()`). If you're looking for ways to manage and verify licenses, please post your feedback in [this issue](https://github.com/YahnisElsts/plugin-update-checker/issues/222). Resources --------- From 57ceef76856301320100022aac7430e28202d508 Mon Sep 17 00:00:00 2001 From: Tim Wiel Date: Wed, 22 Sep 2021 16:25:15 +1200 Subject: [PATCH 6/7] Minor comment change to better reflect code functionality --- Puc/v4p11/Vcs/GitLabApi.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Puc/v4p11/Vcs/GitLabApi.php b/Puc/v4p11/Vcs/GitLabApi.php index a4bc46e..22089c5 100644 --- a/Puc/v4p11/Vcs/GitLabApi.php +++ b/Puc/v4p11/Vcs/GitLabApi.php @@ -372,7 +372,7 @@ if ( !class_exists('Puc_v4p11_Vcs_GitLabApi', false) ): $updateSource = $this->getLatestTag(); } - //3. Do branch if all else fails + //3. Do branch (including master if no latest tag found) if branch is specified OR nothing at all specified if ( empty( $updateSource ) ) { $updateSource = $this->getBranch($configBranch); } From cea29dcaaa3c080d49283cb511ebc4242b3357e4 Mon Sep 17 00:00:00 2001 From: Tim Wiel Date: Thu, 23 Sep 2021 13:48:02 +1200 Subject: [PATCH 7/7] Fixed authentication issues for public repos and re-priortised the order of update checking from Gitlab to match the Github methodology --- Puc/v4p11/Vcs/GitLabApi.php | 101 ++++++++++++++++++------------------ README.md | 29 +++++------ 2 files changed, 64 insertions(+), 66 deletions(-) diff --git a/Puc/v4p11/Vcs/GitLabApi.php b/Puc/v4p11/Vcs/GitLabApi.php index 22089c5..32b62f5 100644 --- a/Puc/v4p11/Vcs/GitLabApi.php +++ b/Puc/v4p11/Vcs/GitLabApi.php @@ -125,51 +125,53 @@ if ( !class_exists('Puc_v4p11_Vcs_GitLabApi', false) ): 'updated' => $release->released_at, 'apiResponse' => $release, )); + $download_url = false; - if ( $this->isAuthenticationEnabled() ) { - $download_url = false; - if ( $this->releasePackageEnabled && isset($release->assets, $release->assets->links) ) { - /** - * Use the first asset LINK that is a zip format file generated by a Gitlab Release Pipeline - * - * @link https://gist.github.com/timwiel/9dfd3526c768efad4973254085e065ce - */ - foreach ($release->assets->links as $link) { - if ( 'zip' === substr($link->url, -3) ) { - $download_url = $link->url; - break 1; - } + if ( $this->releasePackageEnabled && isset($release->assets, $release->assets->links) ) { + /** + * Use the first asset LINK that is a zip format file generated by a Gitlab Release Pipeline + * + * @link https://gist.github.com/timwiel/9dfd3526c768efad4973254085e065ce + */ + foreach ($release->assets->links as $link) { + if ( 'zip' === substr($link->url, -3) ) { + $download_url = $link->url; + break 1; } - if ( empty( $download_url ) ) { - return null; - } - if ( ! empty( $this->accessToken ) ) { - $download_url = add_query_arg('private_token', $this->accessToken, $download_url); - } - - $reference->downloadUrl = $download_url; - } elseif ( $this->releaseAssetsEnabled && isset($release->assets) ) { - /** - * Use the first asset SOURCE file that is a zip format from a Gitlab Release which should be a zip file - */ - foreach ($release->assets->sources as $source) { - if ( 'zip' === $source->format ) { - $download_url = $source->url; - break 1; - } - } - if ( empty( $download_url ) ) { - return null; - } - if ( ! empty( $this->accessToken ) ) { - $download_url = add_query_arg('private_token', $this->accessToken, $download_url); - } - $reference->downloadUrl = $download_url; } + if ( empty( $download_url ) ) { + return null; + } + if ( ! empty( $this->accessToken ) ) { + $download_url = add_query_arg('private_token', $this->accessToken, $download_url); + } + $reference->downloadUrl = $download_url; + return $reference; + + } elseif ( isset($release->assets) ) { + /** + * Use the first asset SOURCE file that is a zip format from a Gitlab Release which should be a zip file + */ + foreach ($release->assets->sources as $source) { + if ( 'zip' === $source->format ) { + $download_url = $source->url; + break 1; + } + } + if ( empty( $download_url ) ) { + return null; + } + if ( ! empty( $this->accessToken ) ) { + $download_url = add_query_arg('private_token', $this->accessToken, $download_url); + } + $reference->downloadUrl = $download_url; + return $reference; + } - return $reference; - } + //If we get this far without a return then obviosuly noi release download urls were found + return null; + } /** * Get the tag that looks like the highest version number. @@ -360,20 +362,17 @@ if ( !class_exists('Puc_v4p11_Vcs_GitLabApi', false) ): * @return null|Puc_v4p11_Vcs_Reference */ public function chooseReference($configBranch) { - $updateSource = null; - //1. Do releases first irrelevant of branches - if ( $this->releaseAssetsEnabled || $this->releasePackageEnabled ) { + if ( $configBranch === 'main' || $configBranch === 'master' ) { + //Use the latest release. $updateSource = $this->getLatestRelease(); + if ( $updateSource === null ) { + //Failing that, use the tag with the highest version number. + $updateSource = $this->getLatestTag(); + } } - - //2. Do tag with the highest version number next if branch is master - if ( empty( $updateSource ) === null && $configBranch === 'master' ) { - $updateSource = $this->getLatestTag(); - } - - //3. Do branch (including master if no latest tag found) if branch is specified OR nothing at all specified - if ( empty( $updateSource ) ) { + //Alternatively, just use the branch itself. + if ( empty($updateSource) ) { $updateSource = $this->getBranch($configBranch); } diff --git a/README.md b/README.md index 30f17b0..236ce23 100644 --- a/README.md +++ b/README.md @@ -263,9 +263,19 @@ BitBucket doesn't have an equivalent to GitHub's releases, so the process is sli 3. Plugins only: Add a `readme.txt` file formatted according to the [WordPress.org plugin readme standard](https://wordpress.org/plugins/readme.txt) to your repository. The contents of this file will be shown when the user clicks the "View version 1.2.3 details" link. #### How to Release a Gitlab Update -A Gitlab repository can be checked for updates using 4 different options. The default is option 4. +A Gitlab repository can be checked for updates using 4 different options. -1. Update from **GitLab Releases using Generic Packages**: +1. Update from any **Gitlab Stable branch** (other than `master` or `main`): + - Point the update checker at any stable, production-ready branch and PUC will periodically check the `Version` header in the main plugin file or `style.css` and display a notification if it's greater than the installed version. + - Add the following code: + ```php + //Add the following code to your main plugin file or `functions.php` file to check for an new update from a non-master branch + $myUpdateChecker->setBranch('stable-branch-name'); + ``` + - Caveats: + - If you set the branch to `main` (the default) or `master` (the historic default), the update checker will look for recent releases and tags first. It'll only use the `main` or `master` branch if it doesn't find anything else suitable. + +2. Update from **GitLab Releases using Generic Packages**: - Use a Gitlab CI/CD Pipeline to automatically generate your update on release using a Generic Package. The benefit of using Generic Package assets over the Source Code assets as it the code can already be built and production ready. - Add the following code: ```php @@ -280,7 +290,7 @@ A Gitlab repository can be checked for updates using 4 different options. The de - [Example .gitlab-ci.yml file using Release Generic Packages for generating a update package from the Sensei-LMS wordpress plugin](https://gist.github.com/timwiel/9dfd3526c768efad4973254085e065ce) -2. Update **GitLab Releases using Source Code Assets**: +3. Update **GitLab Releases using Source Code Assets**: - Create a new release using the "Releases" feature on Gitlab and PUC will periodically check the release version (based on release tag name) and display a notification if the release version is greater than the installed version. - Add the following code: ```php @@ -291,22 +301,11 @@ A Gitlab repository can be checked for updates using 4 different options. The de - PUC will periodically check the release version (based on release tag name) and display a notification the release has a greater than the installed version. -3. Update from any **Gitlab Stable branch** (other than `master`): - - Point the update checker at any stable, production-ready branch and PUC will periodically check the `Version` header in the main plugin file or `style.css` and display a notification if it's greater than the installed version. - - Add the following code: - ```php - //Add the following code to your main plugin file or `functions.php` file to check for an new update from a non-master branch - $myUpdateChecker->setBranch('stable-branch-name'); - ``` - - Caveat: If you set the branch to `master` (the default), the update checker will look for recent releases and tags first. It'll only use the `master` branch if it doesn't find anything else suitable. - - -4. Update from **Tags** on the master branch (default option): +4. Update from **Tags** on the master branch (this is the default option): - To release version 1.2.3, create a new Git tag named `v1.2.3` or `1.2.3`. That's it. - Add the following code: ```php //Add the following code to your main plugin file or `functions.php` file to check for an new update from a non-master branch - //OR don't add any of the 4 options to your main plugin file or `functions.php` $myUpdateChecker->setBranch('master'); ``` - PUC doesn't require strict adherence to [SemVer](http://semver.org/). These are all valid tag names: `v1.2.3`, `v1.2-foo`, `1.2.3_rc1-ABC`, `1.2.3.4.5`. However, be warned that it's not smart enough to filter out alpha/beta/RC versions. If that's a problem, you might want to use GitLab branches instead.