Branch Structure

There are 3 important branches in this repository, each with a role in the deployment process:

• staging
• main
• gh-pages

staging and main are modified directly; gh-pages is modified automatically whenever changes are made to staging and main (e.g. push a commit). In other words, staging and main contain source code that determines what will be generated and deployed to the live site. The gh-pages branch is where those generated files are stored. Changes that we make in staging and main are then reflected in gh-pages branch.

gh-pages

The gh-pages branch is a container for the final, processed version of the site. The folders and files in this branch are ultimately what appear in the browser when visiting the website.

The contributor does not make changes to this branch directly.

The GitHub Action Workflow automatically deploys this code to the GitHub Pages site whenever changes are made in the main or staging branches.

main

The main branch provides the source code for the website. It contains the Markdown (.md) files, HTML (.html) files, images, and styles that are used to generate the final site. When changes are pushed to this branch, the files generated from this branch's contents are placed in the gh-pages branch and the gh-pages is deployed.

The contributor makes changes to the main branch when they want their changes to appear on the site immediately (without testing).

The GitHub Action Workflow builds the files and places the generated files into the gh-pages branch. Then, it re-deploys the GitHub pages site.

staging

The staging branch provides a way of testing changes on a live environment before being made visible by all users. It does this by creating a copy of the live site and placing it in the /staging folder of the website. For example, if the website www.example.com is the Home Page for the site contained in the main branch, then www.example.com/staging is the Home Page for the site contained in the main branch.

The contributor makes changes to the staging that they want to test on the live site before pushing them to the main branch.

The GitHub Action Workflow builds the code in this branch and places it in the /staging folder of the website. Then, it re-deploys the GitHub Pages site.

Typical development processes

The following are processes in which changes can be made to the website, depending on whether the contributor wants to make a separate branch and/or test their changes in staging first. The safest and preferred way is the Low risk method, though it is the most involved and time consuming. For many small, predictable changes, the Medium risk method suffices, as it still has a layer of testing before the changes are visible by the public. Lastly, the High risk method should be avoided unless there is a need to instantly make changes without testing.

Low risk (changes to feature branch and staging)

1. Create a new branch (e.g. my-feature-branch) off of the main branch
2. Make changes in my-feature-branch
3. Create a PR from my-feature-branch to staging
4. When ready, merge the PR into staging (Note: when the triggered GitHub Actions Workflow completes, these changes will be visible under the /staging route of the live site)
5. If everything looks good, create a PR from staging into main
6. Merge the PR into main (Note: when the triggered GitHub Actions Workflow completes, these changes will be visible on the live site)

Medium risk (changes to staging)

1. Make changes in staging (Note: when the triggered GitHub Actions Workflow completes, these changes will be visible under the /staging route of the live site)
2. If everything looks good, create a PR from staging into main
3. Merge the PR into main (Note: when the triggered GitHub Actions Workflow completes, these changes will be visible on the live site)

High risk (changes to main)

1. Make changes in main (Note: when the triggered GitHub Actions Workflow completes, these changes will be visible on the live site)