Goals for today

  1. Continue to practice Markdown syntax in Quarto.

  2. Continue to practice collaboration on GitHub.

  3. Learn to use “Issues” and “Projects” features on GitHub for project management.

  4. Make a version-controlled CV.


Announcement

Please join the lab-chat channel on Slack for communication during the lab.


Exercise 1: Improve your CV (45 minutes)


General instructions

In Lab 1, you started to create a CV using Quarto, but we did not have much time to work on it. Today, you will have more time to continue this exercise and you’ll get your CV version-controlled on GitHub.

Before you start, please create a new GitHub repo named cv-yourname (replace yourname with your name), clone the repo to your computer, and work on your CV in this new repo. If you already have a draft CV from Lab 1, feel free to copy this draft to your new repo.

IMPORTANT NOTE: For the next exercise, you will be paired with another student to peer review the CVs that you have just made. Therefore, if you do not feel comfortable sharing your own CV, feel free to make a CV for one of your favorite scientists or a fictional character instead.

After you are done with this exercise, please make a few obvious typos (~5) in the document, render it, and commit and push the final version to GitHub.


Suggested activities

Here are some suggested activities you can try with your CV. You don’t have to complete all of them; just pick the ones that seem most interesting to you.

  • Center some section titles, e.g.,

    <div style="text-align:center"><strong>Centered and bolded text (HTML)</strong></div>
    
    \begin{center}\textbf{Centered and bolded text (PDF)}\end{center}
    
  • or, for HTML output only, you can add the following CSS to center level 1-3 headers (inline alternative for HTML only):

    ````md
    <style>
    h1, h2, h3 { text-align: center; }
    </style>
    
    ````
  • Right align some text, e.g.,

    Aligned right (HTML) {.content-visible when-format="html"}
    Aligned left (HTML): [Aligned right and italic (HTML)]{style="float:right"}
    Aligned right (PDF) \begin{flushright}\emph{Aligned right and italic (PDF)}\end{flushright}
  • Add some line dividers and/or space between sections, e.g.,

    ---
    <br>
  • Add bullet points and/or numbered lists, e.g.,

    * level 1
        * level 2
    1. item 1
    2. item 2
  • Format certain text in bold, italic, and underline, e.g.,

    ***Bolded and italic text (HTML or PDF)***
    ___Bolded and italic text (HTML or PDF)___
    <ins> Underlined text (HTML) </ins>
  • Insert a picture of yourself at a select location in the document. For this, use the Visual editor since Quarto makes some internal changes to the image file path.

  • render the same qmd file in different output formats and compare the results, or start a new qmd file for outputting in a different format.

  • Use a CV template. If you have LaTeX installed on your computer (see Lab 1 handout for instructions to install LaTeX), you can use some templates:
    https://github.com/mps9506/quarto-cv/tree/main
    https://alexbass.me/posts/resume/
    https://github.com/schochastics/quarto-cv?tab=readme-ov-file



  • For PDF output only, add your favorite equation.

  • Use Google to find and add one or more features to your CV that are not mentioned in this list.

  • Remember to push your changes to GitHub at regular intervals and when you wrap up this first part of the exercise.


Short break (10 minutes)


Exercise 2: Peer review your CV (45 minutes)


Issues and projects

Issues and projects are useful GitHub features that can facilitate your project management, especially in collaborative projects. They can be used for providing feedback, making plans, assigning tasks, and tracking progress. We will explore these useful GitHub features, please follow this detailed tutorial.


General instructions

For this exercise, you will collaborate with a partner to peer review the CVs you just made.

Add your partner as a collaborator for your CV repo. Then, clone your partner’s repo to your computer using RStudio.


Suggested Activities

It is recommended that you go through your peer review process in the following steps.

  1. Use the intentional typos as an opportunity to practice how to resolve merge conflicts, and how to avoid them when possible.

    1. First, both partners could correct a same typo in one partner’s qmd file in slightly different ways. Do not render the qmd file yet. Then, both partners can commit their changed qmd file. One partner can push first, and the other partner will pull, and will get a merge conflict. They can then address this merge conflict, render, push the resolved version to GitHub, and the other partner can pull. After this, partners can switch roles.
    2. Then, partners can correct typos in different lines in one person’s qmd file. Similarly, neither should render at this point. Again, they will both commit their changes, one partner will push first, and when the other pulls, the changes should be merged automatically. They can now render, push, and the other partner can pull.
  2. In the previous step, we emphasized that neither partners should render their changed qmd file before pulling other’s changes. This is because conflicted versions of qmd files can usually be merged without too much of a hassle, but with the rendered markdown, html, or pdf files, you might get unwieldy merge conflicts because of different system configurations between partners. There is, however, a very simple fix to this: the partner who has received the unwieldy merge conflict could just deleted the knitted output, and render the qmd file once merge conflicts (if any) are resolved. Now, try step 1a again, but both partners can render this time.

  3. Use the GitHub’s Issue feature to provide feedback to your partner on their CV.

  4. Create a GitHub Project under the CV repo, and assign the Issues to your partner as a “to-do” item in this project.

  5. Revise your CV according to the feedback from your partner, and respond and close the Issue when the feedback is resolved.

  6. If there is still some time left after you have finished all the steps above, you can either take more time to practice your collaboration skills, or start working on this week’s assignment.


Recap (15 minutes)

Share your findings, challenges, and questions with the class.


END LAB 2