-
Notifications
You must be signed in to change notification settings - Fork 0
/
contributing.qmd
89 lines (55 loc) · 9.15 KB
/
contributing.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
---
title: "Editing the Website"
---
## Overview
This page houses the beginnings of our 'how to edit the website' instructions. Note that this page is <u>primarily for internal use</u> so it assumes you already are a member of the group and have the necessary access to the source GitHub repository. There are a few viable options for contributing to this website. Choose the method that aligns best with your skills and/or the one that sparks the most joy for you.
### Cautionary Conflicts Note
GitHub makes a lot of the technical aspects of collaborating much simpler but there is one thing to watch out for: conflicts. Essentially, <u>GitHub is _not_ Google Docs</u>. This means that while we can edit this website _collaboratively_ we cannot do so _simultaneously_. When multiple people edit the same file in different ways, GitHub doesn't know which set of changes should take priority (and it is often the case that we want both sets of edits!) and so it returns a conflict message that essentially says 'you figure it out human'.
Fortunately the way to avoid conflicts is straightforward: communicate with one another! Before making any edits to the files in this website, reach out to the rest of the group and let them know! This can be as simple as "hey, I'll be working on topic X from 10-11 ET so please don't edit anything in the meantime." For those of you working in GitHub directly you don't really need to worry too much about this because your edits will always take priority but it's good to think about so you don't set the stage for others to encounter conflicts.
### Method 1: Through GitHub
We've done some fancy behind-the-scenes wrangling with GitHub to support this method (see [here](https://quarto.org/docs/publishing/github-pages.html#publish-command) if that is of interest) but the key take-away is that edits made directly in GitHub should "just work." There is however a small caveat to this option: <u>you can only do this if the page you're editing has _no_ "code chunks"</u>. The processing of code chunks is handled slightly differently from 'normal' text and requires a local computer. Even if your changes don't affect code chunks directly it only matters whether or not there are code chunks in the page at all. Hopefully that's not too limiting of a caveat!
Here's what you'll need to do beforehand:
1. Create a [GitHub](https://github.com/) account
2. Make sure you have edit access to [the GitHub repository](https://github.com/lter/eco-data-synth-primer) where the materials live
Once you've done that you can follow these steps to directly affect the website via GitHub! To start, go to the course's [GitHub repository](https://github.com/lter/eco-data-synth-primer) and click the file for the page you want to edit. You can deduce that because the URL of that page will exactly match the file name. For example, let's imagine that we want to edit the contributing page [lter.github.io/eco-data-synth-primer/contributing.html](https://lter.github.io/eco-data-synth-primer/contributing.html). The file that controls this page is `contributing.qmd` which you can be sure of because it shares everything but the file extension with the link.
<p align="center">
<img src="images/github-edits_step-1.png" alt="Screen capture of the landing page of a GitHub repository" width="85%"/>
</p>
Once you're there, click the name of the file you want to edit (for the demonstration purposes we'll click `contributing.qmd`). On the resulting page, you'll want to click the small pencil icon just above and to the right of the website content (see beneath the word "History" in the screenshot below).
<p align="center">
<img src="images/github-edits_step-2.png" alt="Screen capture of the GitHub view of a file" width="85%"/>
</p>
Now you can make any edits you'd like! Don't worry about writing one super long line because when the website "renders" (i.e., builds itself) the text will be automatically wrapped to the width of the screen. In the screenshot below I've added "Here I can edit the website file directly through GitHub" on line 20.
<p align="center">
<img src="images/github-edits_step-3.png" alt="Screen capture of a file being edited in GitHub" width="85%"/>
</p>
Once you're happy with your edits and want them to be sent to the "real" website, you'll need to "commit" those changes. Click the bright blue--or green depending on your GitHub settings--button in the top right. In the small pop-up window that results, type a short description of what purpose your edits serve. **This message is important** because these comments will create the timeline that we can use to see or return to previous versions of the course materials.
<p align="center">
<img src="images/github-edits_step-4.png" alt="Screen capture of the commit message pop-up window as it appears in GitHub" width="45%"/>
</p>
Now you'll find yourself back in the 'viewing' part of GitHub and you should see your edits in the file. However, **your edits are not _yet_ in the live website**. The site must first render your changes. This rendering effort is essentially the computer parsing your edits to a Quarto document (i.e., a `.qmd` file) into the HTML format needed for the website.
You can check the status of this rendering by clicking the "Actions" tab of the repository. You'll see an orange--or red, again depending on your GitHub settings--circle with a progress wheel. After a few minutes that should turn into a blue--or green--check mark. You may notice that the name of the Action exactly matches the text you put in the top field of the commit message pop-up window earlier.
<p align="center">
<img src="images/github-edits_step-5.png" alt="Screen capture of a GitHub Action that is in progress with a little pinwheel circle" width="75%"/>
</p>
Once that Action finishes you'll see a much faster one called "pages build and deployment" show up and go through the same process. This action is tying together the new website (all the unchanged files plus whatever files were changed by your edits) and updating the living website with that content.
<p align="center">
<img src="images/github-edits_step-6.png" alt="Screen capture of a GitHub Action that has finished with a little check mark" width="75%"/>
</p>
Once both of those Actions have finished you should be able to visit the website link and see your edits in the live version! Note that you may need to refresh your browser page to update your cache so if you don't immediately see your edits you may want to wait a moment and refresh the page.
<p align="center">
<img src="images/github-edits_step-7.png" alt="Screen capture of a website with the edits demonstrated in earlier screenshots incorporated" width="85%"/>
</p>
### Method 2: Through RStudio
If you're more confident with a Git-based workflow, you can use RStudio (or any comparable platform) to make edits to the website.
Here's what you'll need to do beforehand:
1. Do the [five setup steps](https://nceas.github.io/scicomp-workshop-collaborative-coding/#workshop-preparation) in this GitHub workshop
2. Install [Quarto](https://quarto.org/docs/get-started/) on your computer
3. Make sure you have edit access to [the GitHub repository](https://github.com/lter/eco-data-synth-primer) where the materials live
4. Clone that repository to your computer
Editing a Quarto website is fairly straightforward once you've handled the prepartory steps outlined above. You'll begin by editing your chosen files and--periodically--committing those changes.
The `.gitignore` should be set up in such a way that you cannot commit files you "shouldn't" be committing but the rule of thumb is that you should feel free to commit either (A) changes to files ending in `.qmd` or (B) anything in the `_freeze/` directory. The `_freeze/` directory is how Quarto stores files that need some amount of computing so that it doesn't waste computing resources re-rendering those files all the time and instead only re-renders when needed. Note that only files with one or more code chunks will ever put anything in that folder.
Our GitHub Actions (see the 'Method 1' tutorial) are set up in such a way that once you push your commits the website should re-build itself automatically. Just wait for the GitHub Actions to complete and/or refresh your browser after pushing and you should see your edits reflected in the website.
While editing you may find the {{< fa terminal >}} `quarto preview` command line call helpful as it will create a new tab in your browser that will dynamically show any edits you make. This is really nice particularly for writing or debugging a code chunk as you'll be able to see the outputs in real time without waiting for the site to render only to find out your code doesn't work as intended.
### Method 3: Through Others
If you'd prefer, you can write the text that you'd like to include in the text editing software (e.g, Microsoft Word, Google Docs, etc.) of your choice. Once you've written it there, send it to someone else on the team who can use one of the preceding methods to get that content integrated. Ideally, hosting through GitHub (and creating this document) empowers you to make edits on your own behalf but if that feels out of reach in this moment **we absolutely still want your insight** so please don't hesitate to go this direction if necessary.