Session 1 guide

Code working group - Session 1

Agenda

• 9:05-9:10: Plan for the next few weeks (Selin)
• 9:10-9:20: Git basics and repository organization / workflow (Nic)
• 9:20-9:30: Sandbox package intro (Selin)
  • Structure
  • Functions
  • Function documentation
• 9:30-9:35: Task explanation (Selin)
• 9:35-9:50: Task demo, or Git basics demo, (Nic)
• Questions

Links

• Toy repository: https://github.com/fungenomics/sandbox
• Dropbox link: https://www.dropbox.com/sh/sg5g15hs33iswpe/AAD4QClrNyVDsu-vjOPkygdua?dl=0

Task

In this task, we'll set up the sandbox repository locally on our own machines, and then add a basic function

Outcomes:

• Understand Git workflow basics
• Understand package structure & function documentation

Steps:

(The 🌟 marks steps that are great habits to use in your regular day-to-day coding)

0. Set up your local env for development
   • Git and ssh keys
   • roxygen2 R package
1. Create an issue on GitHub
2. Clone the sandbox repository to your machine
3. Switch to the develop-private branch
4. Create a new branch, corresponding to your issue
5. Add your function in a new .R file in the R/ directory
6. Document your function: 🌟
   • If using roxygen2 in RStudio, with your cursor inside the function, add the documentation skeleton by going to "Code > Insert Roxygen Skeleton"
   • Otherwise, type out the template
   • Populate the "Title", @param, @return, and @examples fields (as a rule of thumb, @param and @return should tell you what type of object is received/returned - numeric, character vector, list with named slots, etc - and what it should/will contain)
7. Build documentation
   • In RStudio: Rebuild documentation by going to "Build > Document" (if you use the shortcut Cmd + shift + D, it's rebuilding the documentation)
   • From the R command line: Rebuild documentation with roxygen2::roxygenise()
   • At this point, you should see an .Rd file created under man for your function
8. Add & commit your changes with a descriptive message, in the imperative tense
9. Push the commits on your branch to the remote (GitHub) - you will need to create the new branch

What kind of function to add:

1. Takes a numeric parameter
2. Manipulation of the fibonacci vector, using the parameter
3. Returns a numeric output

Examples:

• Raise the vector to the nth power
• Create a new vector which recycles fibonacci n times
• Return the nth element

Resources:

Helpful resources for R package development

• Hadley Wickam's guide to R package development: http://r-pkgs.had.co.nz/
• Package structure: http://r-pkgs.had.co.nz/package.html
• Object documentation: http://r-pkgs.had.co.nz/man.html

Helpful Git basics resources (notes from Nic)

• Git cheat sheet: https://www.atlassian.com/git/tutorials/atlassian-git-cheatsheet
• Understanding git — https://hackernoon.com/understanding-git-fcffd87c15a3 —> This tutorial was recommended by Marie — it covers every you need to get started!
• Pro Git — https://git-scm.com/book/en/v2 —> This is how I personally got started with Git — it covers repos, commits, branching, rebasing, workflows in good detail.
• Knowledge is Power: Getting out of trouble by understanding Git — https://www.youtube.com/watch?v=sevc6668cQ0 —> This is a great video that goes well with Pro Git — you can watch this before, after, or while going through Pro Git.

Helpful Git workflow resources (notes from Nic)

• A guide to GitHub flow: a lightweight workflow — https://guides.github.com/introduction/flow/ —> This covers a simple workflow for project management