build: add deployment previews for vega-lite documentation site

[hydrosquall]

Motivation

• A deployment preview is a hosted version of a static site created just with the contents of this branch
• If this works out, we could add a similar change to deploy the editor site down the line.
• developer-experience: deployment previews for pull requests #9276

Changes

Try configuring https://github.com/rossjrw/pr-preview-action

Testing

• The comment on this PR should link to a version of the docs site that outputs a console.log every time the vega-lite compile function is called.

Notes

• As far as being a part of native Github, this feature is currently only available to Github pages for GH employees ( https://github.com/orgs/community/discussions/7730 )
  • preview timeline? actions/deploy-pages#180 (comment)

[github-actions]

PR Preview Action v1.4.7
🚀 Deployed preview to https://vega.github.io/vega-lite-pr-previews/pr-preview/pr-9277/
on branch gh-pages at 2024-03-03 16:11 UTC

[hydrosquall]

It looks like this action doesn't work The site is built ( https://github.com/vega/vega-lite/tree/gh-pages/pr-preview/pr-9277 ), but the address doesn't work because the repository is not set up to serve from a branch. It looks like you can either have (Github Actions) or (Github Pages) set up, but not both.

I'm going to leave this alone until we have a chance to discuss, as we can avoid needing to configure a custom action if we're willing to use a 3rd party provider (StackBlitz, cloudflare pages, vercel, netlify, etc) to handle this for us. Alternately, we could let the previews be published to a separate repository.

[hydrosquall]

After looking at the size of the pushes to gh-pages, I don't think deploying the preview site based on GH pages is a good idea, even if it were possible to do so inside this repo. Each new PR would generate a diff millions of lines long due to all the compiled JSON examples. Unless our maintainers and contributors remember to not download the gh-pages branch, this is a lot of unnecessary bloat in the github repository. I think this is part of why Github is trying to deprecate the branch-based deployment model, and keep the deployment artifacts outside of Git.

I'm inclined to recommend that we do this without native github actions, and instead choose one of the providers that offer deployment preview for free to open source projects. Let me know what you think @domoritz , and we can go from there.

[nicolaskruchten]

The way I've solved this in the past is not to commit to gh-pages as a child commit of the existing one, but rather as a whole new parent-less commit. This way there are no diffs, just a bunch of orphaned commits that eventually go away or at least don't really bother anyone.

[hydrosquall]

@nicolaskruchten thanks for taking a look. Do you have a link to a public repository where you had set this up?

I'm not sure that the GH pages route for branch deploys will work inside this repo, but maybe what you're describing is something we could try in a repo dedicated to just hosting PR previews, e.g. https://github.com/vega/vega-lite-pr-previews

[nicolaskruchten]

Here you go https://github.com/plotly/plotly.py/blob/master/.circleci/config.yml#L558-L567 ... I was surprised that this worked but it does! The target for this is here https://github.com/plotly/plotly.py-docs/tree/gh-pages (which renders at https://plotly.com/python-api-reference/) and it's always a single commit with no parent. Presumably the other commits are piling up somewhere in Github's infra and getting garbage-collected? I'm not sure but no one has ever complained to my knowledge :)

[nicolaskruchten]

To get deployment previews per-PR is probably a lot trickier than this, though. Incredibly valuable but trickier :) We've done this in the past with Heroku's non-free features, and maybe there's a workflow with a provider with hobby plans? Fly.io doesn't collect on monthly bills under $5 so maybe that's an option since these deployment previews will get very little traffic?

[domoritz]

Thanks for making a POC for this. I think hosting previews in a separate repo sounds great. Alternatively, I've seen vercel/netflify deploy PRs and that could be an alternative. That's what https://github.com/vega/react-vega does for example (@kristw set that up). I don't care either way as long as we don't pollute the main repo.

[domoritz]

Yes

[domoritz]

No. That would be too much noise. I've never had to check dependabot PRs.

[domoritz]

Why not latest?

[hydrosquall]

I was trying to avoid surprise breakages by pinning to a specific version.

[domoritz]

I'm not worried about os updates.

[hydrosquall]

Replaced by #9294