Update github workflow to include staging and develop

[dweng0]

Description

We need a way to easily preview changes ideally when they are in PR mode. The current approach of using GitHub Pages for testing changes in a non-live environment is not ideal because it requires merging all changes into the staging branch. This becomes problematic when multiple changes need to be tested independently, as they cannot be isolated for separate testing.

Note
Cloudflare is seen as a viable solution that to its usage in other projects. So this investigation will focus on leveraging cloudflare to handle deployment of the preview links.

Tasks

• Investigate a workable deployment process for each PR so that a preview URL can be generated. and commented into the PR.
• Investigate the use of Cloudflare's Wrangler based deployments.
• Investigate the use of Github actions with Cloudflare as the deployment step

Deployment using Cloudflare

Cloudflare does not have Quarto as a preset framework. So a config file like Wrangler is required. Wrangler is similar in nature to Github actions but provides less flexibility. We can define a set of variable states and "tell" cloudflare what to run.
There were some problems with Wrangler. There are 3 different versions but more importantly Cloudflare Pages cannot use any of the settings specified in the wrangler documentation other than what is stated on this page.

My investigation showed that no scripts can be run directly inside wrangler due to permissions issues. Therefore Quarto could not be installed. This means that leveraging Wrangler to install Quarto and render the markdown on Cloudflare is not possible. Cloudflare needs to be provided with the compiled static content after Quarto has rendered it

The Investigation code commit is available here

15:12:39.026	sudo: The "no new privileges" flag is set, which prevents sudo from running as root.
15:12:39.026	sudo: If sudo is running in a container, you may need to adjust the container configuration to disable the flag.
15:12:39.029	Failed: Error while executing user command. Exited with error code: 1

name = "docs-autonity-org"
pages_build_output_dir = "./docs"
build = "wget https://github.com/quarto-dev/quarto-cli/releases/download/v1.5.56/quarto-1.5.56-linux-amd64.deb && sudo dpkg -i quarto-${QUARTO_VERSION}-linux-amd64.deb && quarto render"

Deployment using Github Actions

The problem with the previous approach was that Cloudflare cannot compile in the cloud and therefore needs rendered content.

This approach leverages Github actions to handle the rendering of Quarto via Quarto's actions 1, 2, with Cloudflare's action3 used to perform the deployment and provide the output. And finally add-pr-comment4 is used to create the comment, leveraging the generated output from Cloudflare's action.

Problems with this setup.

Following testing on PR #231. Investigation showed that Cloudflare would not "comment" directly on the PR and provide a preview link, so an additional step is required to take the generated output from the cloudflare step and use it to post on the PR.

PR #231 has an action that is currently implementing this approach.

Recommended approach

I suggest we test the GitHub Actions approach

1. Leverage Quarto's actions to prepare and render the site
2. Use Cloudflares actions to create the preview and generate the output necessary to provide the url.
3. Use a pr-comment action to comment out the url to the PR.

As part of the investigation process, PR #231 has been created using github actions that contain these steps.

---

Legacy Information (for Reference Only):

---

Description

With the addition of new features to the documentation site, it would be beneficial to set up a staging server. This will allow us to thoroughly test new changes before pushing them live.

Additionally, it makes sense to establish a develop branch for feature development. Changes can be pushed to develop for testing before merging into master, aligning our workflow with best practices used in our other projects.

• Add develop and staging branches (off of master)
• Configure repo for gh_pages
• update readme development workflow

[aiman]

Note AFAIK GH pages can only host a single "site" for a repo, not multiple sites. So it would not be possible to have different staging and develop sites at the top-level, unless they were on different URL paths.

[aiman]

We should investigate using Cloudflare to preview site per pull request.