Collaborative renv and git exercise

Practice with renv and git workflows

---

Initial code description

code/01_make_output1.R

• generates random numbers
• saves numbers as a .rds object in output/ folder

code/02_render_report.R

• renders report.Rmd

report.Rmd

• reads random numbers generated by code/01_make_output1.R
• makes a scatter plot of one set of random numbers against another set
• the points are colored in based on the third set

---

Collaborative renv exercise description

Determine users

Assign one partner to be User A and one partner to be User B.

Confirm code base is stable

User A should download and unzip the project files. If needed, move the files/directory to a desired location on User A's computer either using the command line or a file browser.

Once the files are in the desired location, confirm that User A can build the report by executing make.

• If the report does not build, correct code until it builds correctly
• If make is not working properly, you can alternatively run the code "by hand" from the command line.
  • Change your terminal directory to the project folder.
  • Run Rscript code/01_make_output.R
  • Run Rscript code/02_render_report.R

User B does not need to download and unzip the project folder because they will download it in a later step from User A's GitHub.

Initialize renv project library

User A should initialize an renv library.

1. Be sure that User A has the renv package installed.
   • e.g., you could run "renv" %in% row.names(installed.packages())
   • If the above command returns FALSE, install the renv package using install.packages('renv')
2. In an R console, use setwd and getwd to confirm that the current working directory in the R console is the project directory.
3. Initialize the project library by running renv::init()
4. Confirm that the project directory now includes the following files:
   • .Rprofile
   • renv.lock
   • renv/ folder
   • renv/settings.dcf
   • renv/activate.R
   • renv/.gitignore

Initialize git repository

User A should initialize a local git repository.

1. Use git init to initialize a git repository in your project directory folder
2. Appropriately use git status, git add, and git commit to create your first commit. The commit should include:
   • all contents of the code directory
   • report.Rmd
   • README.md
   • Makefile
   • .gitignore
   • the output directory (i.e., the output/.gitkeep file)
   • all of the renv-associated files referenced in the previous section

Create a GitHub repository

User A should create a GitHub repository using the following steps.

1. Log in to GitHub and create an empty GitHub repository.

   • be sure to select the option not to add a README nor a license.
   • choose any name for the repository you like

2. User A uses git remote add origin git@github.com:<user_a_github_name>/<user_a_repo_name> to add User A's GitHub repository as a remote of User A's local repository named origin.

   • replace <user_a_github_name> and <user_a_repo_name> with User A's GitHub user name and GitHub repository name, repsectively
   • be sure to use the "ssh" style syntax for adding a remote and not "https". I.e., your command should be git remote add origin git@github.com:... and not git remote add origin https://github.com/....
   • You can confirm what web address was used to add the remote by executing git remote -v. - If the output of git remote -v shows that origin points to https://github.com/<user_a_github_name>/<user_a_repo_name>, then User A should remove the origin remote using git remote remove origin try Step 2 again.

3. Use git push origin <your_branch_name> to push User A's local repository to GitHub.

   • <your_branch_name> is probably main, but it may be master for some of you

4. Refresh the web page for User A's GitHub repository's to confirm that the push was successful.

---

Fork and clone the repository

User B should now fork and clone User A's repository on GitHub using the following steps.

1. User B should navigate to https://github.com/<user_a_name>/<user_a_repo> and click "Fork" to create a fork of User A's repository.

• replace <user_a_name> with User A's GitHub user name
• replace <user_a_repo> with User A's GitHub repository name
• Recall that this creates a copy of User A's GitHub repository on User B's GitHub.

2. User B should use cd in their terminal to navigate to a directory where they wish to download User A's repository.
3. User B should execute git clone git@github.com:<user_b_name>/<user_b_repo> to clone the repository.

• be sure to use the git@github.com:<user_b_name>/<user_b_repo> syntax and not https://github.com/<user_b_name>/<user_b_repo> syntax.
• You can confirm what web address was used to add the remote by executing git remote -v.
• If the output of git remote -v shows that you accidentally used https:// syntax in your git clone command then User B should remove the origin remote using git remote remove origin and then re-add the remote using "ssh"-style syntax: git remote add origin git@github.com:<user_b_name>/<user_b_repo>.

3. User B should confirm that a folder called <user_b_repo> was added to the current working directory of their terminal.

• E.g., use cd <user_b_repo> and ls to change working directory into the newly downloaded repository and list its contents.

Synchronize project environment

Before starting development, User B should ensure that their project environment is synchronized with the renv.lock file.

1. Confirm that User B has the renv package installed.
   • e.g., you could run "renv" %in% row.names(installed.packages())
   • If the above command returns FALSE, install the renv package using install.packages('renv')
2. In an R console, use setwd and getwd to confirm that the working directory is the project directory.
3. Once you are positive that you are in the correct working directory, restore the package library using renv::restore().
4. Confirm that the report builds, e.g., by running make or by executing the contents of code/01_make_output.R and code/02_render_report.R.
   • If you are running code interactively in the R console, be sure that the package environment is activated!
   • It is recommended to complete this step via make or running code from the command line.

Update the repository and submit a pull request

User B will now make a new branch and make updates to User A's repo on that branch. The updates made by User B will change the color of the points in the scatter plot in the final report. In particular, User B will use the wesanderson package to define a new color scheme to update the code.

User B should complete the following steps:

1. Create and checkout a new branch called wes by executing git checkout -b wes.

• recall that this simultaneously creates and checks out a new branch called wes
  • confirm that User B has switched to the new branch by executing git branch

2. In the R console, be sure that the project environment is activated.
   • e.g., you could check .libPaths() and confirm that the renv/ directory in your project folder is the first file path returned
   • If the project environment is not activated, activate it: use setwd and getwd to confirm that your project directory is your working diretory; use renv::activate() to activate the project environment.
3. Once the project environment is activated, install the wesanderson package into the project library by running install.packages('wesanderson').

At this point User B has installed a new package in the project's library and is now ready to make changes to the code.

1. Make the following modifications to report.Rmd:
   • replace line 48 (colors <- 1:4) with the following line

colors <- wesanderson::wes_palette("Zissou1", 4)

2. Confirm that the report can be built and that the colors of the scatter plot have changed.
   • Again, it is recommended that this step be completed at the command line using make or running e.g., Rscript code/01_make_output.R
   • If you are running code interactively in the console, be sure your project environment is activated.

At this point User B has now confirmed that their changes are functional and working as expected. Now we need to add the wesanderson package (and any dependencies) to the renv.lock file to prepare for a PR.

1. In the R console, be sure that the project environment is activated.
2. Run renv::status() to check whether your project is synchronized with the lock file.
   • You should get a message saying that there are packages used that are not recorded in the lock file.
3. Run renv::snapshot() to update the lock file.

Now User B is ready to submit a PR to User A.

1. Use git add and git commit to make a new commit along the wes branch that includes updates to report.Rmd and renv.lock.
   • include a meaningful commit message
2. Push the wes branch to GitHub.
   • git push origin wes
3. Submit a pull request to User A's repository.
   • the pull request should request that User B's wes branch be merged into User A's main branch.

Finally, User B should rename their compiled report so that it can be submitted as part of the assignment.

1. Make sure the working directory of your terminal is your project directoy.
2. Use mv report.html report_wes.html to rename the report.
3. Submit report_wes.html as part of the assignment.

---

Test out pull request code

User A will now fetch the code submitted by User B, synchronize their project library, test out the code, and eventually merge it into their main branch, thereby closing the pull request.

1. User A should add User B's repository as a remote.

   • git remote add <user_b_remote_name> https://github.com/<user_b_name>/<user_b_repo>
     • in this case, it's OK to use the https:// syntax, because User A does not need to push to User B's repository.
     • "ssh"-style syntax would also be fine
   • replace <user_b_remote_name> with whatever you would like to call this remote
   • replace <user_b_name> with User B's GitHub user name
   • replace <user_b_repo> with User B's GitHub repository name

2. User A should fetch from User B's repository.

   • git fetch <user_b_remote_name>
   • Recall that this command downloads the contents of User B's repository, but does not yet put them on any of User A's local branches.
   • To confirm the fetch worked properly, User A could, but does not need to, execute git checkout <user_b_remote_name>/wes
     • This will put you in "detached HEAD" state and will update the files in User A's repository to the version of the files submitted by User B.
     • To return to User A's main branch User A should run git checkout main. This will return the files in User A's repostiory to their own version of the files (i.e., not including the contributions from User B).

3. User A should create and checkout a new branch named wes from the <user_b_remote_name>/wes branch.

   • git checkout -b wes <user_b_remote_name>/wes
   • Recall that this creates a new branch in User A's repository called wes that looks exactly like the branch fetch'ed from User B's remote.

Now User A is ready to test out the code on the wes branch.

1. In an R console, use getwd and setwd to confirm that the working directory is the project directory.

2. Use renv::restore() to synchronize the project library.

   • This likely will involve User A (automatically) installing wesanderson to the project library.

3. Once the project environment is synchronized with the lock file, User A should try to build the report.

   • E.g., they should use make or Rscript (with terminal working directory equal to the project directory) to build the report.

4. When User A is satisfied that the code works as expected, they should merge the wes branch into main.

   • git checkout main
   • git merge wes

5. User A should push the updated main branch to GitHub.

   • git push origin main
   • Both users should now see User B's pull request as "merged" on GitHub.

More changes, User A

1. User A should create and checkout a new branch called brewer.

   • git checkout -b brewer
   • Recall that this simultaneously creates and checks out a new branch called brewer in User A's local repository.

2. In the R console, be sure that the project environment is activated.

   • e.g., you could check .libPaths() and confirm that the renv/ directory in your project folder is the first file path returned
   • If the project environment is not activated, activate it: use setwd and getwd to confirm that your project directory is your working diretory; use renv::activate() to activate the project environment.

3. Once the project environment is activated, install the RColorBrewer package into the project library by running install.packages('RColorBrewer').

4. Make the following modifications to report.Rmd:

   • replace line 48 with the following line

colors <- RColorBrewer::brewer.pal(4, "Set1")

5. Confirm that the report can be built and that the colors of the scatter plot have changed.
   • Again, it is recommended that this step be completed at the command line using make or running e.g., Rscript code/01_make_output.R
   • If you are running code interactively in the console, be sure your project environment is activated.

At this point User A has now confirmed that their changes are functional and working as expected. Now we need to add the RColorBrewer package (and any dependencies) to the renv.lock file and remove wesanderson from the lock file.

1. In the R console, be sure that the project environment is activated.
2. Run renv::status() to check whether your project is synchronized with the lock file.
3. Run renv::snapshot() to update the lock file.

Now User A is ready to commit changes and merge their brewer branch into main.

1. Use git add and git commit to update the brewer branch with the changes that have been made to renv.lock and report.Rmd

2. Merge brewer into main.

   • git checkout main
   • git merge brewer

3. Push to GitHub git push origin main.

Finally, User A should rename their compiled report so that it can be submitted as part of the assignment.

1. Make sure the working directory of your terminal is your project directoy.
2. Use mv report.html report_brewer.html to rename the report.
3. Submit report_brewer.html as part of the assignment.

---

User B update local repository and fork

1. User B should add a remote called upstream that points to User A's GitHub repository.

   • git remote add upstream https://github.com/<user_a_name>/<user_a_repo>
     • in this case, it's OK to use the https:// syntax, because User B does not need to push to User A's repository.
     • "ssh"-style syntax would also be fine here

2. User B should fetch from the upstream remote and merge upstream/main into main

   • git fetch upstream
     • Recall that this downloads the contents of User A's repository (i.e., the upstream remote) to User B's computer; however, it does not add User A's commits/branches to User B's local branches.
   • git checkout main
     • User B needs to be on their main branch to merge in changes from User A's GitHub repository.
   • git merge upstream/main
     • Recall that this will update User B's local files on the main branch to look like User A's files from GitHub.
     • To confirm, User B could look in report.Rmd and locate the RColorBrewer-associated code.

3. User B should synchronize their project envirinoment.

   • From an R console, be sure that the project environment is activated.
   • Once activated, run renv::restore() to synchronize the project environment.

4. User B should confirm that the report builds and that the scatter plot colors have changed.

5. User B should push their main branch to origin.

   • git push origin main

---

Reverse roles and repeat

If you have time, reverse roles of User A and B and repeat the exercise. However, you should not delete the GitHub repository associated with the first run through of the exercise, as you will be graded based on that repository.