GH Pages / Release workflow improvements

[jrfnl]

During the release of Requests 2.0.0, there were three things which went wrong regarding the automated update of the GH Pages website:

1. The expected PR to update the GH Pages site did not get created.
   This was caused by an incorrect tag selection in the workflow.
   For the 2.0.0 release, this was fixed by manually triggering the workflow.
2. The PR which got created after the tag was pushed, but before the release was published contained the wrong version number in the generated API documentation.
   This was caused by the script updating the phpDocumentor config using the wrong GitHub API endpoint.
   For the 2.0.0 release, this was fixed by manually updating the GH Pages PR with a search/replace done for the incorrect version number.
3. Lastly, the GH Pages PR was merged before the release was published, which led to the site still showing the version number for the previous release in various places.
   This is caused by the fact that during the site deploy, these version numbers are retrieved from the GH API, but there is only access to release information, not to tag information.
   For the 2.0.0 release, this was fixed by manually pushing a small whitespace change to the ghpages branch after the release was published to get it to regenerate,

This PR attempts to address these issues.

Commit details

API docs: adjust script to use latest tag instead of release

The GitHub API unfortunately does not have a /tags/latest endpoint, so to get the latest tag, we need to get all tags, then sort them based on semantic version names and then get the latest from the stack.

This implements this in the script which updates the phpDocumentor configuration. The tag name is used as the API docs title in the generated docs.

GH Actions: tweaks to the website update workflow

This commit makes various tweaks to the website update workflow based on the experiences round the 2.0.0 release:

• Run every time a tag is pushed.
  The previously included tag selection was only in place to prevent the script from running in case we'd still tag a 1.x release. As there is no intention to update the 1.x branch anymore, the tag selection can be removed.
• The branches-ignore addition is experimental.
  It is not unusual that in the ramp up to a release, a PR from develop to stable is created before all PRs for the release have been merged.
  Round the 2.0.0 release, this led to every PR merge which caused an update to the release PR to generate a new draft PR for the website update as the release contained the new workflow (which was therefore seen as "changed"), while that feature is only really intended for PRs to develop.
  Let's see if adding stable to branch-ignore for pull requests will prevent this in the future.
  the PR, but after all changes have been made).
• Also made two minor tweaks to the pull request creation inputs.
• Workflows which create PRs do not trigger any other workflows which would normally run on a PR.
  This means that the test-ghpages.yml workflow in the ghpages branch is not triggered for the auto-generated PRs, while doing a test build to ensure there are no Jekyll errors when the website is deployed is kind of helpful.
  As this check only involves two steps, I'm duplicating these into this workflow to ensure the ghpages build test is still executed for the auto-generated PRs.

Release checklist: minor tweaks

While GH Pages does have access to the GitHub API during the site generation and deploy, the information it can access is limited.

I've verified that there is no access to the tags information. This means that for those places in the site which automatically update based on information from the GH API, we need to rely on release information, i.e. the release needs to have happened already for the information to be updated correctly.

This means that the merging of the GH Pages PR needs to happen after the release has been published.
This is now documented as such in the release checklist.

Ref: https://github.com/jekyll/github-metadata/blob/master/docs/site.github.md

[schlessera]

Workflows which create PRs do not trigger any other workflows which would normally run on a PR.
This means that the test-ghpages.yml workflow in the ghpages branch is not triggered for the auto-generated PRs, while doing a test build to ensure there are no Jekyll errors when the website is deployed is kind of helpful.
As this check only involves two steps, I'm duplicating these into this workflow to ensure the ghpages build test is still executed for the auto-generated PRs.

We can also trigger one workflow from the other via https://docs.github.com/en/rest/reference/actions#create-a-workflow-dispatch-event. Is that something we want to look into to keep the workflows DRY? Not sure it is worth the testing hassle in this case, tbh...

[jrfnl]

We can also trigger one workflow from the other via https://docs.github.com/en/rest/reference/actions#create-a-workflow-dispatch-event. Is that something we want to look into to keep the workflows DRY? Not sure it is worth the testing hassle in this case, tbh...

I actually did look into that, but that would only complicate things in this case.

1. Such a workflow would need to be run in a separate job, it cannot be run as a "step" in the current job.
2. The re-usable workflow would need to be passed information on which branch to check out, but the branch name is dynamically created in the createpr job and jobs don't have access to information from other jobs.
3. And even then, the PR branch may not even exist, as if the workflow resulted in no changes to the GH Pages site, the PR branch never gets created and won't be available.

All in all, I decided it was not worth the hassle for this particular workflow.

Ref: https://docs.github.com/en/actions/learn-github-actions/reusing-workflows