Merge pull request #1 from lter/dev_alt-text

feat: alt text for all images in the workshop

_quarto.yml

@@ -8,7 +8,7 @@ execute:
 
 website:
   title: "SciComp Workshop - Collaborative Coding with GitHub"
-  favicon: images/logos/scicomptools_hex.png
+  favicon: images/logos/hex_scicomptools.png
   repo-url: https://github.com/lter/workshop-github
   repo-actions: [issue]
   twitter-card: true
@@ -53,15 +53,15 @@ website:
     center: "Copyright 2024, NCEAS"
     background: secondary
   margin-footer: |
-    <img src="images/logos/nceas_logo_square.png" width="40%"/>
-    <img src="images/logos/lter_logo_square.png" width="40%"/>
+    <img src="images/logos/nceas.png" alt="Logo for NCEAS (National Center for Ecological Analysis and Synthesis)" width="40%"/>
+    <img src="images/logos/lter.png" alt="Logo for the LTER Network Office" width="40%"/>
 
 format:
   html:
     theme:
        light: _extensions/lter/lter_scss-theme/theme_lter-edu-light.scss
        dark: _extensions/lter/lter_scss-theme/theme_lter-edu-dark.scss
-    mainfont: Lato
+    mainfont: Open Sans
     toc: true
     link-external-newwindow: true
     link-external-icon: false

branches.qmd

@@ -41,7 +41,7 @@ However, deletion of the branch either locally or via GitHub **must** come *afte
 As you can see from the above text and the below diagram, branches have a few more moving parts than the Git and GitHub operations we've discussed so far. That said, they can be a powerful tool in service of collaborative work because you can have multiple branches active at the same all working on separate tasks. This approach can be an easy (or at least eas*ier*) workflow for working together while avoiding conflicts (again, see "Appendix A: Conflicts").
 
 <p align="center">
-<img src="images/branches/git-branch-workflow.png" width="75%"/>
+<img src="images/branches/git-branch-workflow.png" alt="Graphic demonstrating the process of using brances on a Git/GitHub repository. Essentially you pull the latest changes before making a branch, then make the branch and work in it. Once you're happy with your progress, you can submit a pull request to merge your work back into the 'main' branch and then you delete your branch" width="75%"/>
 </p>
 
 Now we've gone over this big picture overview, let's walk step-by-step through creating, working in and ultimately merging branches!
@@ -53,27 +53,27 @@ Before you create a branch, **<span style="color:blue">pull</span>** from GitHub
 That done, click the **<span style="color:purple">purple</span>** button in the Git tab of RStudio that shows two rectangles connected by a diamond at right-angles from one another.
 
 <p align="center">
-<img src="images/branches/branches-1-new-branch-button.png" width="75%"/>
+<img src="images/branches/branches-1-new-branch-button.png" alt="Screenshot of the set of buttons in RStudio's Git pane" width="75%"/>
 </p>
 
 In the resulting dialogue box, give your new branch an informative name. In this example we haven't given our new branch a great name but in a "real" repository you will greatly appreciate having concise but descriptive branch names.
 
-Once you're happy with the name, click **"Create"** (you can ignore the other options and buttons on this dialogue box).
+Once you're happy with the name, click "**Create**" (you can ignore the other options and buttons on this dialogue box).
 
 <p align="center">
-<img src="images/branches/branches-2-name-new-branch.png" width="65%"/>
+<img src="images/branches/branches-2-name-new-branch.png" alt="Screenshot of the menu that opens when you click the purple 'create branch' button in RStudio. Includes a text field for the branch name as well as a some other checkboxes/options (that can be safely left at their default settings in many cases)" width="65%"/>
 </p>
 
 This will create a confirmation message that is superficially similar to the format of messages returned by other Git actions.
 
 <p align="center">
-<img src="images/branches/branches-2b-success-dialogue.png" width="75%"/>
+<img src="images/branches/branches-2b-success-dialogue.png" alt="Screenshot of the text returned when you create a branch in RStudio" width="75%"/>
 </p>
 
 You will also notice that in your Git tab where previously it said "main" it now shows whatever name you chose for your branch.
 
 <p align="center">
-<img src="images/branches/branches-2c-new-branch.png" width="75%"/>
+<img src="images/branches/branches-2c-new-branch.png" alt="Screenshot of RStudio's Git pane where it can be seen that the branch name has changed to the new branch created earlier" width="75%"/>
 </p>
 
 ## Work in the Branch
@@ -97,13 +97,17 @@ On that page GitHub will helpfully have created a button at the top of the scree
 
 Click that button.
 
-![](images/branches/branches-6-pull-request-start.png)
+<p align="center">
+<img src="images/branches/branches-6-pull-request-start.png" alt="Screenshot of a repository in GitHub where the 'compare and pull request' button is being offered because GitHub detected a push in the branch" width="100%" />
+</p>
 
 You will then be prompted to write a title and message for your pull request to give some broader context for what the branch does. This is especially valuable if you are not the one reviewing pull requests as this can help someone quickly familiarize themselves with what you have done.
 
 Once you're satisfied with your title and message, click the <span style="color:green">green</span> "Create pull request" button.
 
-![](images/branches/branches-7-pull-request-msg.png)
+<p align="center">
+<img src="images/branches/branches-7-pull-request-msg.png" alt="Screenshot of GitHub when you open a pull request and are prompted to give it a title and description" width="100%" />
+</p>
 
 That done, GitHub will send you to a page that looks very much like a Github issue (see the chapter on issues). At the top is whatever title and message you just wrote when opening the pull request following by a list of all of the commits in that branch.
 
@@ -115,27 +119,37 @@ You or your team can post messages on a pull request as needed (see the text box
 
 If you are ready to merge a pull request from your branch into the "main" branch click the intuitively-named <span style="color:green">green</span> "Merge pull request" button.
 
-![](images/branches/branches-8-active-pull-request.png)
+<p align="center">
+<img src="images/branches/branches-8-active-pull-request.png" alt="Screenshot of an open pull request on GitHub" width="100%" />
+</p>
 
 GitHub will open another text box where you can add a commit message to your acceptance of the pull request. If whoever opened the pull request was sufficiently detailed in their opening comment(s) this may not need to be terribly detailed but it can't hurt!
 
 Once your message is written, click the <span style="color:green">green</span> "Confirm merge" button.
 
-![](images/branches/branches-9-pull-request-accept-msg.png)
+<p align="center">
+<img src="images/branches/branches-9-pull-request-accept-msg.png" alt="Screenshot of the menu that opens on GitHub when you click 'merge pull request' where you are prompted to add an optional description before clicking 'confirm merge'" width="100%" />
+</p>
 
 The green 'open' buttons will change to purple and will use the "merge" icon of two streams combining. As with GitHub issues you can continue to post comments on a merged pull request if you feel it will be valuable for posterity to do so.
 
 GitHub will also handily create a "Delete branch" button at the bottom of the pull request's timeline. We recommend that you click it given that your branch's purpose is served and having irrelevant branches clutters your GitHub and may even cause problems if you have two similarly-named branches where one has been merged and the other has not.
 
-![](images/branches/branches-10-successful-merge.png)
+<p align="center">
+<img src="images/branches/branches-10-successful-merge.png" alt="Screenshot of a closed pull request on GitHub with a 'delete branch' button provided" width="100%" />
+</p>
 
 After you click "Delete branch" it will be replaced by a "Restore branch" button so you could always reclaim it if need be.
 
-![](images/branches/branches-11-deleted-branch.png)
+<p align="center">
+<img src="images/branches/branches-11-deleted-branch.png" alt="Screenshot of a pull request on GitHub after the 'delete branch' button has been clicked and replaced by a 'restore branch' button" width="100%" />
+</p>
 
 Finally, return to the "Code" tab of your GitHub repository and you can see that the changes we implemented in the branch are now part of the repository's "main" branch. The branch name is displayed just above the last commit message and the first file in the repository but below the different tab names.
 
-![](images/branches/branches-12-github-repo-post-merge.png)
+<p align="center">
+<img src="images/branches/branches-12-github-repo-post-merge.png" alt="Screenshot of the GitHub repository after the pull request was merged showing that the most recent commit was the merging of the PR" width="100%" />
+</p>
 
 ## Update Local Repository
 
@@ -144,19 +158,21 @@ Now that GitHub has been told to integrate your branch content with the "main" b
 First, click the name of the branch to see all the branch names in your repository and select the "main" branch to flip your local repository over to that branch.
 
 <p align="center">
-<img src="images/branches/branches-14-switch-local-to-main.png" width="75%"/>
+<img src="images/branches/branches-14-switch-local-to-main.png" alt="Screenshot of RStudio after the branch name was clicked (in the Git pane) showing that the new branch and the 'main' branch are options" width="75%"/>
 </p>
 
 Notice though that our script went back to the pre-merge version but don't panic!
 
 In order to update your local version of the repository all that you need to do is click the **<span style="color:blue">pull</span>** button. This brings the content you just merged via GitHub (see above) into your local repository.
 
-![](images/branches/branches-15-notice-outdated-script.png)
+<p align="center">
+<img src="images/branches/branches-15-notice-outdated-script.png" alt="Screenshot of RStudio after showing the original (pre-pull request) version of the script" width="100%" />
+</p>
 
 You will get a success message indicating the changes to each file in the same way any other **<span style="color:blue">pull</span>** would. You can notice between this picture and the previous that the code automatically changes when the **<span style="color:blue">pull</span>** is complete.
 
 <p align="center">
-<img src="images/branches/branches-16-pull-merged-repo.png" width="75%"/>
+<img src="images/branches/branches-16-pull-merged-repo.png" alt="Screenshot of the message in RStudio when you pull after merging a pull request on GitHub" width="75%"/>
 </p>
 
 Now that you merged your branch with the main branch on GitHub and pulled that merged content down to your local version you have successfully start-to-finish used branches in your workflow.

conflicts.qmd

@@ -29,7 +29,7 @@ So the basic steps to resolving a merge conflict using RStudio are as follows:
 We can see those steps visually in the following workflow diagram:
 
 <p align="center">
-<img src="images/conflicts/git-conflict-workflow.png" width="60%"/>
+<img src="images/conflicts/git-conflict-workflow.png" alt="Graphic indicating the process of resolving a conflict when one occurs. After the initial conflict (caused when pushing a file from your machine differs from the GitHub version of that file), the combined file is auto-generated on your machine and you must then resolve the changes manually. These changes can then be committed and pushed up to GitHub" width="60%"/>
 </p>
 
 ## How Merge Conflicts Happen
@@ -39,86 +39,98 @@ Below is a common scenario that can lead to merge conflicts and then the steps t
 Let's say we have a repository that we've shared with a collaborator. Currently there's a `README.md` and only one script, `test-script.R`, in it.
 
 <p align="center">
-<img src="images/conflicts/conflicts-1-example-repo.png" width="80%"/>
+<img src="images/conflicts/conflicts-1-example-repo.png" alt="Screenshot of a simple GitHub repository containing only a single script and a README" width="80%"/>
 </p>
 
 `test-script.R` contains one line. Suppose we want to work on this script and add more lines to it.
 
 <p align="center">
-<img src="images/conflicts/conflicts-2-test-script.png" width="80%"/>
+<img src="images/conflicts/conflicts-2-test-script.png" alt="Screenshot of a script with a single comment line" width="80%"/>
 </p>
 
 Let's go commit our edits. The green lines highlight the fact that we've added two new lines to our script, lines 2 and 3. We type out our commit message, and click **Commit**.
 
-![](images/conflicts/conflicts-3-birds.png)
+<p align="center">
+<img src="images/conflicts/conflicts-3-birds.png" alt="Screenshot of a staged file with a commit message where a vector of bird names is being added" width="100%" />
+</p>
 
 Great! The message "Your branch is ahead of 'origin/main' by 1 commit" lets us know that everything is proceeding smoothly. Suppose that we decided to take a break and stepped away from our computer.
 
-![](images/conflicts/conflicts-4-birds-commit.png)
+<p align="center">
+<img src="images/conflicts/conflicts-4-birds-commit.png" alt="Screenshot of RStudio after a successful commit" width="100%" />
+</p>
 
 Then, unbeknownst to us, our collaborator made their edits to the same script and committed and pushed their changes to the GitHub repository. At the moment, here is what the shared repository looks like.
 
 <p align="center">
-<img src="images/conflicts/conflicts-5-flowers.png" width="80%"/>
+<img src="images/conflicts/conflicts-5-flowers.png" alt="Screenshot of the earlier GitHub repository where someone has made edits to the script" width="80%"/>
 </p>
 
 When we get back to our computer, we're ready to **<span style="color:green">push</span>** our changes to GitHub, but an error shows up. Basically, it is telling us that our GitHub repository contains changes that we do not have on our local computer. To remedy this, the message suggests that we pull the changes from GitHub to our machine to catch our local machine back up.
 
-![](images/conflicts/conflicts-6-birds-push.png)
+<p align="center">
+<img src="images/conflicts/conflicts-6-birds-push.png" alt="Screenshot of the message you get when a push is rejected because of a conflict" width="80%" />
+</p>
 
 After clicking **<span style="color:blue">Pull</span>**, we get a new error message: "Merge conflict in test-script.R".
 
-![](images/conflicts/conflicts-7-birds-pull.png)
+<p align="center">
+<img src="images/conflicts/conflicts-7-birds-pull.png" alt="Screenshot of the message you get when you pull after getting a conflict and Git (through RStudio) warns you that it created an automatic merge" width="80%" />
+</p>
 
 Looking closer, the merge conflict prompted a new version of `test-script.R` to pop up. This version contains our edits and our collaborator's edits, along with the delimiter lines that start with `<<<<<<<`, `=======`, and `>>>>>>>`. Git is urging us to manually fix the conflicted lines before continuing.
 
 <p align="center"/>
-<img src="images/conflicts/conflicts-8-conflicted-lines.png" width="80%"/>
+<img src="images/conflicts/conflicts-8-conflicted-lines.png" alt="Screenshot of a script where there was a conflict now having rows of symbols separating the two versions of the conflicting line" width="80%"/>
 </p>
 
-Our file now has an **[U]{style="color:orange"}** icon, which stands for an unresolved merge conflict.
+Our file now has an **<span style="color:orange">U</span>** icon, which stands for an unresolved merge conflict.
 
 <p align="center"/>
-<img src="images/conflicts/conflicts-9-unresolved.png" width="80%"/>
+<img src="images/conflicts/conflicts-9-unresolved.png" alt="Screenshot of Rstudio's Git pane where the script with conflict now has two orange 'U' icons (for 'unresolved')" width="80%"/>
 </p>
 
 In general terms the steps that come before a merge conflict are displayed in the visual below. Note that though this has visual similarity to the workflow diagrams throughout this bookdown we do not recommend intentionally causing a merge conflict :)
 
 <p align="center"/>
-<img src="images/conflicts/git-conflict-cause.png" width="60%"/>
+<img src="images/conflicts/git-conflict-cause.png" alt="Graphic of three vertical rectangles, the left and right ones labeled 'you' and 'other' while the center has a happy cloud emoji. Both side rectangles pull a given file from Github then edit that file in different ways. The first person is able to successfully push without issue but the second person to push gets a conflict" width="60%"/>
 </p>
 
 ## Resolving Merge Conflicts
 
 So how do we resolve this merge conflict? We need to edit the script so that it looks like how we want it. We can either pick our lines to keep, our collaborator's lines, some combination, or something new altogether. Be sure to communicate with your collaborator to discuss exactly how it should be fixed. After merging the changes wherever appropriate, delete the delimiter lines.
 
 <p align="center">
-<img src="images/conflicts/conflicts-10-resolved.png" width="80%"/>
+<img src="images/conflicts/conflicts-10-resolved.png" alt="Screenshot of the script where the special characters have been removed and the conflict has been resolved" width="80%"/>
 </p>
 
 Then stage, commit the changes, and push them to GitHub!
 
-![](images/conflicts/conflicts-11-commit-resolved.png)
+<p align="center">
+<img src="images/conflicts/conflicts-11-commit-resolved.png" alt="Screenshot of RStudio where the once-conflicted script is being staged and committed with issues resolved" width="100%" />
+</p>
 
 Perfect! We've fixed the merge conflict!
 
 <p align="center"/>
-<img src="images/conflicts/conflicts-12-push-resolved.png" width="80%"/>
+<img src="images/conflicts/conflicts-12-push-resolved.png" alt="Screenshot of the success message from RStudio when a push works as desired" width="80%"/>
 </p>
 
 Let's check back on the shared repository. The latest commit shows that we've successfully pushed our changes to GitHub.
 
 <p align="center">
-<img src="images/conflicts/conflicts-13-merged.png" width="80%"/>
+<img src="images/conflicts/conflicts-13-merged.png" alt="Screenshot of a GitHub repository with the the repaired file included" width="80%"/>
 </p>
 
 <p align="center">
-<img src="images/conflicts/conflicts-14-checking-merged.png" width="80%"/>
+<img src="images/conflicts/conflicts-14-checking-merged.png" alt="Screenshot of the repaired file in Github showing the latest changes" width="80%"/>
 </p>
 
 Navigating to the commit history, we see that first we committed our changes, then our collaborator committed and pushed their changes, causing a merge conflict since we were editing the same lines in the same file. To resolve this, we edited those lines directly in our RStudio and committed and pushed our changes once more. Finally, the merge conflict is resolved and all the necessary changes are merged.
 
-![](images/conflicts/conflicts-15-commit-history.png)
+<p align="center">
+<img src="images/conflicts/conflicts-15-commit-history.png" alt="Screenshot of the commit history of the GitHub repository showing where the conflict appears in the history" width="100%" />
+</p>
 
 ## Tips on Avoiding Merge Conflicts