This is a small PR that:
- adds a `fixtures/Gemfile-github-pages`, the minimum gemfile necessary to build the site
- adds a new Actions workflow to build the site with that gemfile
In the future, this should prevent issues like #1074, where we push a change that passes the `jekyll` CI but fails to build on `github-pages` (and its dependencies - which in this case, was an older version of ruby sass).
(to be honest - not super happy with the code duplication, but I also think we'll have different build matrices for the different versions, so I'm fine with this for now)
Part of (but does not close) #1145.
This PR adds a `deploy.yml` to match [what's in our template repository](https://github.com/just-the-docs/just-the-docs-tests). I think it would be a great idea for us to match parity, especially:
- so that it's easier for us to help users & debug
- so that if we move to Jekyll 4 (likely soon), the transition is seamless
- so that we can explore adding custom items to the build step
Before merging this, we'll also need to change the source of the Pages deploy to actions (from the current branch deploy).
tl;dr:
- replaces `jekyll/jekyll` with actions-native container
- changes Jekyll version targets to be explicit: `[3.9, 4.3]`
- fixes CI bug from today
I've **temporarily changed the branch protection rules** so we can merge this PR in.
## Motivations
A handful of motivations for me doing this:
- immediately: in writing #1071, I noticed that our CI is broken; this is due to an issue with the `jekyll/jekyll` container (see below)
- generally: I would like to make our CI as close to what our users would be using; I think the vast majority of our users use pages or actions, rather than the container itself
- nit: building `3.8.5` is *really slow* (takes ~ 3 minutes), and now each matrix strategy takes ~ 30 seconds with no cache!
More on each of those points now!
### Immediate Problem: `sass-embedded`
Starting today, CI fails on `main`. #1071 has one example ([CI log](https://github.com/just-the-docs/just-the-docs/actions/runs/3752287338/jobs/6374267086)), and I was able to repro this on a whitespace change with the `README`.
Several notes:
- building locally, with pages, or with Netlify does not fail; for example, the deploy preview for #1071 still works
- the error has to do with native extensions (of which `sass-embedded` is one of them) not being built properly for musl c linux; changing the pinned version of `sass-embedded` to a previous version does *not* resolve this problem
- it's not transparent what has changed: the `jekyll/jekyll` image itself has not been updated in over a month, but, something in the container (which was not pinned) must have changed and forced an error with compilation
Given that *our users* won't encounter this problem, this reads easily as a CI problem to me - we should resolve our pipeline (and not change user code/artifacts).
### Bigger Picture: `jekyll/jekyll`
Disclaimer: I have never really liked that we use `jekyll/jekyll` as part of our CI pipeline. Let me outline why and why I think this change is a good idea.
Broadly, our CI should closely match how our users use just the docs. After fielding support requests, looking at our big players, etc., I think the most common deployment methods are:
1. using native GitHub Pages. Recently, [GitHub has moved this to use GitHub Actions and their containers](https://github.blog/2022-08-10-github-pages-now-uses-actions-by-default)
2. using GitHub Actions explicitly, like what's provided in our template
3. "out-of-the-box" CD from providers like Netlify, Vercel, or Fly
In contrast, I have met few users using the `jekyll/jekyll` or `jekyll/builder` containers; of course, this is still anecdotal.
Thus, I think our CI should match the common denominator in the vast majority of our user base, which is *not* using the community container, but instead a standard linux container + bolting on Ruby tooling. Given that GitHub Pages is likely our biggest userbase, I think we should match it - which means, using Actions-specific containers (what's in this PR).
Furthermore, I think it's more likely that a user who wants a container is more knowledgeable about deployment and can resolve problems not caught by CI by themselves and/or submit an issue to GitHub, so switching off of this is fine; now, our CI will better match users who are less familiar with CD (and are likely to just use Pages out of the box).
I also will point out that `jekyll/jekyll` is **not a first-party container**, even though the namespace makes it seem like it is; it's maintained by [envygeeks](https://github.com/envygeeks/jekyll-docker). While this is very kind of them, it adds an external dependency that I would prefer to avoid.
### Build Time and `3.8.5`
This is short, but `3.8.5` isn't the latest `3` release; it's not even the latest minor patch. Since it's a "stale" container, pulling it takes a really long time (upwards of 3 minutes).
Bumping to the latest minor shouldn't affect downstream users, and has faster CI for us - which means quicker dev turnaround :)
This is a PR with three key changes:
1. Consolidate two identical CI files, `ci.yml` and `ci-master.yml` into one file
2. Consolidate two almost-identical jobs (`jekyll-build-*`) into one job with a strategy matrix
3. Update various dependencies/platforms
* Node: `12.x` -> `16.x` (only in CI); `12.x` has been EOL for a while
* Ruby: `2.6` -> `2.7`; `2.6` just reached EOL
* `actions/checkout` -> `v2` -> `v3`
* switches `jekyll/builder` to `jekyll/jekyll`, since we don't actually use any of the features in `jekyll/builder`
## on our CI philosophy
In working on this, I have a couple of questions:
1. We don't actually use our `Dockerfile` that we provide. Does this make sense? Should we be running CI with this instead?
2. Is there a specific reason that we're using `jekyll/jekyll`? Notably, this isn't an official package, but a community-driven one. Does it match what's used by GitHub Pages?
3. Do we have to use any docker image at all? For example, what if we just rely on the `setup-ruby` action?
* one advantage of this is that it's much easier for us to test across multiple OS versions; we just need to have a strategy matrix for OS and do windows, macos, ubuntu, etc.
* another advantage is that we can easily test different ruby versions in conjunction with different jekyll versions
Eventually, I would like to see us test across:
* different Jekyll versions
* different OSes
* different Ruby versions
but perhaps that might be too aggressive. Happy for any feedback on this PR or those questions!
Matt Wang
Flo
Patrick Marsceill