Purpose

• Solves concurrency issues within PSR's CI workflow
• Updates PSR Documentation for GitHub Actions recommended workflow
• Resolves: Slow default branch updates due to concurrency #1201

Rationale

See comment in issue #1201. Adds the documentation update to inform users on how to avoid concurrency issues while using the --commit mechanism (generally required for an updating changelog).

How did you test?

I ran through a series of live tests on my fork's GitHub actions workflow on the default branch. First was an push to master during the testing phase prior to release. Second test was the new push had a sleep build into it to make the release job extra long to where I could guarantee a push during the release job (and it not cancel due to concurrency but detect that upstream had moved and self-abort). The third push removed the arbitrary sleep and successfully released since there was no change in the upstream branch. The third push pipeline also waited its turn for the job concurrency to allow it to start in the odd case that it was faster to get through testing than the other previously started pipeline. Not really applicable to PSR but was important to evaluate that cancel-in-progress: false actually had the other pipeline wait its turn.

How to Verify

You should prep the commits for the following before walking master up the chain of commits pushing as you go because timing is critical for this evaluation.

# 1. create temporary branch to pre-stage actions
git checkout -b prep master

# 2. Add a fake fix or feature commit on top of the current (i modified spacing in a file)
# this ensures a release is triggered
git commit -m 'fix: a fake commit'

# 3. Insert a `sleep 1m` into the release job beginning step that resets the branch to the workflow sha
vim .github/workflows/cicd.yml
git commit -m 'fix: a fake commit - cicd workflow modified'

# 4. Revert the previous commit and adjust message to be valid conventional commit
git revert HEAD
git commit --amend -m 'fix: the 3rd pipeline - removes delay on workflow'

# 5. push to default branch to trigger the first workflow
git checkout master
git merge prep~2
git push
git merge prep~1

# 6. Monitor resulting pipeline is during the validation workflow concurrency stage and
# push the next modification to cause a cancelation of current testing
git push
git merge prep

# 7. Monitor the 2nd resulting pipeline for when it enters the release job and hits the arbitrary sleep.
# When it hits the sleep, push this next commit
git push

# 8. Monitor the 2 pipelines in different tabs and you should see the 3rd pipeline pause at its release job
# due to its concurrency directive

# 9. Monitor the 2nd pipeline that has now reached the upstream change detection step and it should
# fail with the message that upstream has changed, aborting release.

# 10. Lastly, on the 3rd pipeline it should successfully release the proper new version to
# include pushing to the remote as it will not detect a change in the upstream and continue with release.

PR Completion Checklist

• Reviewed & followed the Contributor Guidelines

• Changes Implemented & Validation pipeline succeeds

• Commits follow the Conventional Commits standard
  and are separated into the proper commit type and scope (recommended order: test, build, feat/fix, docs)

• N/A Appropriate Unit tests added/updated

• N/A Appropriate End-to-End tests added/updated

• Appropriate Documentation added/updated and syntax validated for sphinx build (see Contributor Guidelines)