Adds GH Pages Workflow

[johnedquinn]

Relevant Issues

• None

Motivation

The PartiQL Maintainers expressed the desire to make it easier to update the specification and have more tangible impact. As a mechanism for tackling these issues, I wanted to allow the tip-of-head specification to always be rendered.

Description

• This PR adds a GH Pages Workflow.
  • The head fork has GH Pages set up already. See the live site here.
  • On pushes to main, this will build using docker and place the HTML in the gh-pages branch.
• This PR also makes a few small changes:
  • We set versions explicitly to ensure that our builds are reproducible -- especially considering the fact that we don't maintain the Gemfile.lock. I ran into build issues because of this.
  • I modified how we perform releases. This matches how we perform releases for other projects such as PLK.
  • I removed the -it flag for running docker interactively -- this is because GH Actions doesn't allow this.
  • I updated how we retrieve the date of publication. I now do it by the last git commit date -- this ensures that when we checkout a tag, we can run it, and it gives us consistent dates.
  • I also updated the section links/anchors. See the documentation here. Now, we can send links to sections easily to each other.

Moving Forward

We will want to update how we perform releases. In my opinion, we need to update the revision numbers, tag, build on the tag, attach the generated HTML/PDF to the release assets, and update the development version.

Other Notes

• If approved, do NOT merge this for me. I need to enable GH Pages and create a dedicated branch before this workflow runs. I haven't done it yet as I wanted the maintainers' feedback before modifying the repository.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[am357]

Thanks for creating this automation! left two comments.

[am357]

From the Conversation note:

I updated how we retrieve the date of publication. I now do it by the last git commit date -- this ensures that when we checkout a tag, we can run it, and it gives us consistent dates.

I know we have added this to the release process but will there be a situation where the latest commit is not corresponding to a tag, i.e., changes not released yet?

[johnedquinn]

Yes, intentionally. So, when we automatically release to GH pages, it'll grab the tip-of-head's date. However, when we release a version, the exact commit will be tagged. Checking out that commit and running this will always give us the release date matching that of the tagged commit.

[am357]

Just to clarify further: so the page that we will see in the website is not necessarily the released version? if so, would it make sense to automate the release and as part of that publish for website?