Actions deployment

[i-baumann]

@cranmer this branch should contain the additional config files needed to use Actions to deploy the site. I'm not able to test it out on this branch since I don't have permission to point Pages to a new URL for this repo for testing.

I tried this out with a more complex deployment elsewhere for a different site and it built successfully, so this should work.

Squash and merge commit message

* Add renv config files and the associated renv lock file for exact environment reproduction.
* Add GitHub Actions based publishing of the website using GitHub Actions as the
  publishing source for GitHub Pages.

[cranmer]

Awesome, thanks @i-baumann! I might ask @matthewfeickert to review and test at some point since he does a lot of this.
The site is live and we just sent an email to respondents about the results and the site, so I don't want to do a test that might lead to downtime right now. Maybe we can convert to GitHub actions in a week or two.

[i-baumann]

Once this is merged we'll probably need to render locally once with quarto publish gh-pages. Actions should build it from the root directory of the gh-pages branch on push at that point, but if not we might need to point it in that direction manually. Not sure how it will behave when we've previously been building from docs with pre-rendered files.

docs will probably also be unnecessary at that point but we should keep it for folks using the template who might want to go that route instead.

[matthewfeickert]

I can't comment on the R stuff, but I would suggest using a GitHub Actions based deployment over branches.

[matthewfeickert]

I'm going to merge in these suggested changes and then if things are passing I'll do another review and squash and merge the PR in the morning (Europe time).

Thanks for this PR @i-baumann!

[matthewfeickert]

The site is live and we just sent an email to respondents about the results and the site, so I don't want to do a test that might lead to downtime right now. Maybe we can convert to GitHub actions in a week or two.

@cranmer I've gone ahead and tested the deployment on my fork with the state of this PR and it works as expected. Here's my fork's website that got deployed via GitHub Actions: https://matthewfeickert.github.io/open_source_survey_results/

This all LGTM, so if you agree I'll write a summary commit message and get this merged, unless you would prefer for there to not be any more deployments until next week (I think this should be fine to just deploy, given that it works).

[i-baumann]

@matthewfeickert thanks a ton for looking at this! Could you also update the readme to reflect your changes?

[i-baumann]

This is going to be a great example of deploying with Actions beyond what's available in the Quarto documentation. If this and #2 are merged I propose maintaining a separate branch that preserves docs/ and demonstrates what the repo with a deployment from docs/ would look like for the sake of the template remaining accessible to users of any skill level and familiarity with Pages & Quarto. Quarto/RMarkdown sites generally aren't deployed with Actions and docs/ is meant to be kept under version control in those cases.

[matthewfeickert]

Quarto/RMarkdown sites generally aren't deployed with Actions and docs/ is meant to be kept under version control in those cases.

Uh oh. Can you link me to Quarto docs on this? I'll see some of the Quarto team at SciPy and can talk with them there, but at first glance it seems like the Quarto team is recommending things that the GitHub Actions teams would actively discourage as (if I understand correctly) support for gh-pages branch deployment is intended to go away in the future.

[i-baumann]

at first glance it seems like the Quarto team is recommending things that the GitHub Actions teams would actively discourage as (if I understand correctly) support for gh-pages branch deployment is intended to go away in the future.

Ahhhh, ok, this is good to know.

This is just anecdotal, but I can't think of any cases where I've come across a repo or tutorial for Quarto sites (at least from the R user side of things) where folks didn't appear to be just locally rendering site content to docs/, pushing docs/, and then pointing Pages there. It's also the first method their docs cover. That's primarily why I chose to deploy the site that way rather than using Actions or quarto publish gh-pages locally.

quarto publish gh-pages just automates the branch deployment process from locally-rendered content as far as I can tell. It avoids placing main branch site content under version control but just pushes content in gh-pages instead. Here's an example from a test repo.

This template will be a great example of how to use Actions to deploy a survey results site, especially if gh-pages deployment is on the way out. I just want to avoid leaving potential first-time Quarto and/or Pages users with the impression that using Actions is the primary or only way to deploy their site.

[cranmer]

Would it make sense to put some of the comments here about gh-pages and this approach to actions in an issue in the quarto repo, or maybe @matthewfeickert plans to talk to their developers about it in person at SciPy first.

[cranmer]

@matthewfeickert this all looks good. Thanks for deploying and testing on your own fork.

[matthewfeickert]

Would it make sense to put some of the comments here about gh-pages and this approach to actions in an issue in the quarto repo

I should collect my references and open up an Issue on GitHub to see where they are planning on going.