docs_release.yml and docs_stable.yml conflict

[wshanks]

For the last two releases, I have had to restart the docs_stable.yml workflow. It fails in the "Deploy stable" / Run JamesIves/github-pages-deploy-action@v4 step. It fails like:

 Switched to a new branch 'github-pages-deploy-action/gk4l0au0n'
/usr/bin/git commit -m Deploying to gh-pages from @ qiskit-community/qiskit-experiments@c7d41beb5693db3b719fb00f7f9611433ac61c15 🚀 --quiet --no-verify
Force-pushing changes...
/usr/bin/git push --force ***github.com/qiskit-community/qiskit-experiments.git github-pages-deploy-action/gk4l0au0n:gh-pages
To https://github.com/qiskit-community/qiskit-experiments.git
 ! [remote rejected]     github-pages-deploy-action/gk4l0au0n -> gh-pages (cannot lock ref 'refs/heads/gh-pages': is at e3ef96ee7ec8f150964914dee18c4de819a04605 but expected a6c334a53747bc6c319c4c8faf85c06ae3acab59)
error: failed to push some refs to 'https://github.com/qiskit-community/qiskit-experiments.git'
Running post deployment cleanup jobs… 🗑️
/usr/bin/git checkout -B github-pages-deploy-action/gk4l0au0n
Reset branch 'github-pages-deploy-action/gk4l0au0n'
/usr/bin/chmod -R +rw github-pages-deploy-action-temp-deployment-folder
/usr/bin/git worktree remove github-pages-deploy-action-temp-deployment-folder --force
Error: The deploy step encountered an error: The process '/usr/bin/git' failed with exit code 1 ❌
Notice: Deployment failed! ❌

I think the problem is that docs_stable.yml and docs_release.yml both trigger off of a new tag. The both make updates to the docs and try to push to the same gh-pages branch, so only one of them can have its push go through cleanly without a merge/rebase.

I think there are a few ways this could be addressed:

1. The same content is being pushed to the top level and to stable/(version). Maybe one workflow could push to both places instead of using parallel workflows? However, the split into two workflows was done intentionally in Deploy docs to GitHub Pages #1356:

   The docs_release.yml and the docs_stable.yml workflows split the current docs.yml workflow into two phases. This change is useful to have more control over what versions we want to deploy. With the old workflow, we needed to deploy everything in a specific order to have the latest version as the unversioned one on the website. With the two workflows, we will be able to re-deploy stable versions when necessary.

2. We could keep separate workflow files but have the _release workflow trigger on tag and push to both places and have the _stable workflow not be triggered by tag. It could only be triggered manually for the re-upload case. The risk here is the files falling out of sync.
3. Going back to the one workflow option, maybe it could push stable/(version) every trigger but only push to top level when triggered from the main branch? I think the case where we would want the ability to re-deploy stable versions would only come up when triggering off of the stable branches?
4. Keep the two files but changing the triggering somehow so that one of them does not start until the other has finished.

[wshanks]

@arnaucasau Do you have a recommendation here? I think option 3 seems nice if I am not overlooking a reason why it is not a good idea.

[arnaucasau]

Hey @wshanks! It's good to see that you are still using the workflows!

Yeah, I think you are right with only wanting to re-deploy stable versions from the stable branches.

However, with option 3, you'll lose the ability of pushing a stable version to the top level. For example, if you need to publish a new patch version (e.g. bug fixes), if you make the changes to the latest stable branch, you might need to trigger the workflow from there instead of from the main branch.

I think option 4 is also a good idea. In reality there's no need of having the latest version stored in stable/ (gh branch) until the next release, but correct if I'm wrong here. With that in mind, you could give priority to the docs_release.yml and run docs_stable.yml afterwards.