Adding releases to GitLab API

[timwiel]

PR to add release capability to GitLab API with two options for assets:

• release asset download auto generated source zip file
• OR release asset download from a release generic package asset

Fixes issue #449

For information about release generic packages

• Gitlab Release Documentation
• Gitlab Release Assets as Generic Package Documentation
• Example .gitlab-ci.yml file using Release Assets as Generic Package for generating a package from the Sensei-LMS wordpress plugin

[YahnisElsts]

Thank you for the PR! I have a few questions and suggestions:

• How does this handle upcoming releases? Those probably shouldn't show up as updates until the released_at date actually arrives.
• What happens if the repository contains one or more releases but the developer did not call either enableReleasePackage() or enableReleaseAssets()? If I'm reading the code correctly, it appears that getLatestRelease() will find the release and return a reference without a download URL. This would look like a confusing behaviour to someone not familiar with the code. I think we should do one of the following instead:
  • Set $releaseAssetsEnabled = true by default so that getLatestRelease() can return something useful without additional configuration. This is my preferred option.
  • Change chooseReference() or getLatestRelease() so that it doesn't even try to retrieve releases if both $releaseAssetsEnabled and $releasePackageEnabled are set to false.
• While it's probably safe-ish to assume the first item in the sources list will be the generated ZIP file, we don't really need to take that risk. I think it would be more future-proof to just walk the sources array in a foreach loop and pick the first item where format equals zip.

[timwiel]

No worries - I'm happy with all those suggestions

I'll work on pushing some more changes to the PR to reflect your suggestions

[timwiel]

I've completed all those suggestions ...

I erred on setting a order of priority for the update checks in the chooseReference() based on the following order:

1. releases with generic packages
2. releases with source code assets
3. branch name other than master
4. master with tagnames (which is the default if no option is added by user to functions.php other than the connection setup

I've updated the README.md to outline this as well

I hope that's all ok

[YahnisElsts]

I don't think that order is going to work because it would be the opposite of how the update checker works with GitHub and BitBucket. For those hosting services, PUC only looks for releases or recent tags if the developer hasn't specified a custom branch. Let's move that option to the top:

1. branch name other than master (or main, which seems to be the new default)
2. releases with generic packages
3. releases with source code assets
4. master with tagnames

Also, it seems that the upcoming_release field is not mentioned anywhere in the Releases API documentation. Is that an undocumented API feature?

[timwiel]

PR updated as suggested :-)

the upcoming_release flag does seem to be undocumented but I've found reference to it here:

• https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29577
• https://gitlab.com/gitlab-org/gitlab-foss/-/commit/e674e62a0dd33eb4e0819de50f5f5074de3c0303

I've also created a PR for the Gitlab API documentation to be updated

[YahnisElsts]

All right, that seems fine. I'll merge it now.