Automated publishing workflow

[joshuagl]

Automate publishing the specification to GitHub pages via Github Actions.

My current proposal is:

1. a CI workflow will build each PR and publish to an appropriately named directory in the gh-pages branch, i.e. this PR might be published to wip/pulls/143 (and then would be browsable at theupdateframework.github.io/specifcation/wip/pulls/143). The workflow would also update the PR with a link to the rendered document.
2. a cleanup workflow would run periodically and compare the children of wip/pulls to open PRs, removing any children of wip/pulls for which there isn't a corresponding open PR
3. a release workflow will be triggered on changes to master, and:
   1. make a release on GitHub with a corresponding versioned tag
   2. build the spec for that release and publish it to the latest directory of the gh-pages branch
   3. also publish the built spec to a versioned subdirectory of the gh-pages branch
   4. update a listing page (index.html?) to point to the versioned subdirectory (the listing will enable browsers to find: the latest spec, specific versioned spec releases, and the most recent draft)
   5. NOTE: once this is done we need to update theupdateframework.io to point to the generated latest specification (and index of published versions)
4. a draft workflow will be triggered on changes to draft, and:
   1. build the spec in the draft branch
   2. publish the spec to a draft subdirectory of the gh-pages branch
5. a nag workflow will be triggered on changes to master and file an issue requesting draft is updated

Questions:

• Should we be signing spec releases (and therefore not doing automated releases on push to master)?
• Is the cleanup workflow necessary or, for the sake of a ~200K per PR, should we retain history for the PRs?

Originally posted by @joshuagl in https://github.com/theupdateframework/specification/issues/143#issuecomment-762334990

• [ ] PRs trigger a build and publish to a wip/pulls subdirectory of the gh-pages branch
• [ ] Updated master branch triggers a release (tag in repo and published release on GitHub)
• [ ] Release triggers a build and publishes to both latest and versioned subdirectories of gh-pages branch (and updates index)
• [ ] theupdateframework.io updated to link to published specification on theupdateframework.github.io/specification
• [ ] Updated master branch files an issue to rebase draft branch
• [ ] Updated draft branch builds the spec and publishes it to the draft subdirectory of the gh-pages branch

[lukpueh]

IIRC https://github.com/theupdateframework/specification/pull/143#issuecomment-762334990 pp. has some discussion about your questions.