Use Primer Spec

[aarmaane]

Closes #45. Changed one of the notes into a "callout" box. Not sure if that was a good choice or if there were other places where it would useful to do as well.

[seshrs]

Cool! But you’ll also need to add a GitHub Pages action in the .github folder, and change the repo settings to deploy via Action. More details here: https://github.com/seshrs/build-primer-spec-action#setting-up-github-pages-deployment

[aarmaane]

Thanks for the pointers! I'm curious what the custom action does differently from GitHub's default "Deploy from a branch" action? I tried the default on my fork and it seems to render the spec without issue.

[seshrs]

(Oh sorry I thought I replied.)

The TLDR is that the custom action guarantees that your website can use all of Primer Spec features. Currently, the only value-add is that the action generates downloadable PDFs for each page; but in future, we could theoretically add more features that rely on build-time customizations.

[jamesjuett]

Should we also include a Gemfile and Gemfile.lock now?

[awdeorio]

Should we also include a Gemfile and Gemfile.lock now?

Adding those is tricky. You gotta use certain versions of Ruby and bundler to be compatible with CI. I just pushed them.

[aarmaane]

ffi-1.17.1-x86_64-linux requires rubygems version >= 3.3.22, which is
incompatible with the current version, 3.2.33
Error: The process '/opt/hostedtoolcache/Ruby/3.0.7/x64/bin/bundle' failed with exit code 5

The action is failing on my fork. Did I misconfigure it or do the versions need to be changed?

[seshrs]

Should we also include a Gemfile and Gemfile.lock now?

Adding those is tricky. You gotta use certain versions of Ruby and bundler to be compatible with CI. I just pushed them.

Now that custom GitHub Actions and Pages deployment is a thing, I wonder if I should rewrite Primer Spec to remove our dependency on Jekyll…

Btw the Gemfile is only needed to preview the pages locally: https://eecs485staff.github.io/primer-spec/docs/USAGE_ADVANCED.html#previewing-locally

[seshrs]

ffi-1.17.1-x86_64-linux requires rubygems version >= 3.3.22, which is
incompatible with the current version, 3.2.33
Error: The process '/opt/hostedtoolcache/Ruby/3.0.7/x64/bin/bundle' failed with exit code 5

The action is failing on my fork. Did I misconfigure it or do the versions need to be changed?

Hmm… I can try looking later today. (Another reason I want to move away from Jekyll!)

[jamesjuett]

Btw the Gemfile is only needed to preview the pages locally: https://eecs485staff.github.io/primer-spec/docs/USAGE_ADVANCED.html#previewing-locally

+1 that's along the lines I was thinking, in terms of consistency with our other repos and the contributing instructions for local preview. (Even though it may not really be that crucial for local previews on the UTF tutorial.)

[awdeorio]

Maybe just ripping out the lockfile is the way to go!

[aarmaane]

Is it a bad idea to use the same Gemfile.lock from another working repo? I tested it with the tutorial repo's Gemfile.lock and the action works.

[jamesjuett]

Is it a bad idea to use the same Gemfile.lock from another working repo? I tested it with the tutorial repo's Gemfile.lock and the action works.

I believe this will work fine.

The issue appears to be that a freshly generated Gemfile.lock will include newer versions of packages, including the incompatible ffi. There are a of possible fixes we could try, including specifying an older version of ffi or any other incompatible packages in the Gemfile.

But, using the Gemfile.lock from the tutorials repo will simply require the exact same versions of all dependencies as in that repo, which seems fine. (We may eventually need to bump something and update the Gemfile.lock in either place, but I don't think there's anything wrong with borrowing from the other repo for now.)

@seshrs @awdeorio does this make sense?

[awdeorio]

That should be mostly fine. It would also be fine to skip the lockfile.

[aarmaane]

The action works now, so I think this is ready to merge. Whoever merges just needs to change the repository settings to "deploy via action" since I don't have access to that.

[jamesjuett]

LGTM. I'll merge and update the settings.