Merge pull request #273 from UBC-DSCI/trevorcampbell-patch-1

add new workflows to readme

Author: trevorcampbell

README.md

@@ -18,12 +18,6 @@ See [the license file](LICENSE.md) for more information.
 
 Building the book requires Docker (instructions here: [https://docs.docker.com/get-docker/](https://docs.docker.com/get-docker/)).
 
-### Contributing 
-Primary development in this repository happens on the `main` branch. If you want to contribute to the book,
-please branch off of `main` and make a pull request into `main`.
-
-The `production` branch contains the source material for the live, publicly viewable HTML book.
-
 ### Build locally
 
 You can build the HTML version of the book on your own machine by running
@@ -38,15 +32,34 @@ You can build the PDF version of the book on your own machine by running
 ```
 in the root directory of this repository. The book can be viewed in a PDF reader by opening `source/_build/latex/python.pdf`.
 
-### Update build environment
+### Contributing 
+Primary development in this repository happens on the `main` branch. If you want to contribute to the book,
+please branch off of `main` and make a pull request into `main`. You cannot commit directly to `main`.
+
+The `production` branch contains the source material corresponding to the current publicly-viewable version of the book website.
+
+The `gh-pages` branch serves the current book website at https://python.datasciencebook.ca.
+
+### Workflows
+
+#### Book deployment
+
+You can update the live, publicly viewable HTML book by making changes to the `source/` folder in the `production` branch (e.g. by merging `main` into `production`).
+GitHub will trigger a rebuild of the public HTML site, and store the built book in the root folder of the `gh-pages` branch.
+
+#### `main` deploy previews
+
+Any commit to `source/**` on the `main` branch (from a merged PR) will trigger a rebuild of the development preview site served at `https://python.datasciencebook.ca/dev`.
+The built preview book will be stored in the `dev/` folder on the `gh-pages` branch.
+
+#### PR deploy previews
 
-You can update the build environment for the book by making changes to `Dockerfile` in the root of the repository in the `main` branch.
-If you push any changes to the `Dockerfile` on the `main` branch, GitHub will trigger a rebuild of the docker image,
-push it to DockerHub, and update the `build_html.sh` script and book deploy GitHub action with the new image tag.
+Any PR to `source/` will trigger a build of a PR preview site at `https://python.datasciencebook.ca/pull###`, where `###` is the number of the pull request.
+The built preview book will be stored in the `pull###/` folder on the `gh-pages` branch.
 
-### Update public html
+#### Build environment updates
 
-You can update the live, publicly viewable HTML book by making changes to the `source/` folder in the `production` branch.
-If you push any changes to the `source/` folder on the `production` branch, GitHub will trigger a rebuild of the public HTML site.
+Any PR to `Dockerfile` will trigger a rebuild of the docker image, push it to DockerHub, and update the image tags in the `build_html.sh` and `build_pdf.sh` scripts on the PR automatically.
+This new build environment will be used for the PR deploy preview mentioned above.