ibeem-msu/ibeem-collaborative-coding

source code for the IBEEM-sponsored workshop "Collaborative Coding for Scientific Research: Git, GitHub, and open science"

Workshop materials for Collaborative Coding for Scientific Research: Git, GitHub, and open science

This (will be) course materials for a workshop to be held at Michigan State University, sponsored by the MSU Institute for Biodiversity, Ecology, Evolution, and Macrosystems (https://ibeem.msu.edu)

About

These are the source files for the materials, to see the materials, go to the rendered book on github pages (URL pending).

Development

The book is coded based on R Markdown and bookdown (https://github.com/rstudio/bookdown). For more about bookdown package, see the page "Get Started" at https://bookdown.org/yihui/bookdown/

To install the packages needed, use renv

After cloning/downloading these files, in R use

install.packages('renv')
renv::init()

To preview the web-version of book use

bookdown::serve_book()

You may generate a copy of the book in bookdown::pdf_book format by calling bookdown::render_book('index.Rmd', 'bookdown::pdf_book'). More detailed instructions for using bookdown are in the bookdown book https://bookdown.org/yihui/bookdown/build-the-book.html.

---

This work is licensed under Attribution-ShareAlike 4.0 International

ibeem-collaborative-coding's Issues

fix typo in "issue" in section 2.6

Section on handling merge conflicts...

Was talking with a few people at the conference today and they made a good point that they didn't know what to do when conflicts did come up. I think our branching approach avoids some of this, but it might be worth just quickly touching base on what to do when merge conflicts arise.

glossary has deep sub-headings

glossary numbering is rendering as 9.0.1, 9.0.2,

maybe change sub-headings from ### to ## ?

Also should remove bold which I don't think is needed for headings (usually already bolded).

Pull request exercise with our book

write up an in-class exercise for participants to fork this book/repository and add examples to our examples. Need to add category of example

• package
• project
• reference

Prior to the exercise, walk through it once as a group. Someone volunteers an example repo, we then ask the group to categorize and why, then do a fork and a PR in our personal github accounts with the example.

can github to edit the markdown directly rather than get book down running

advanced user: provide a PR story for how they were able to contribute to a project, or an interaction they had on gitub.

ch on licensing

short chapter covering practical aspects of licensing and using someone else's code in your work

Ideas for improving on Workshop #1

• Break up lecture by inserting mini-exercise bits after introducing a concept (E.g., introduce an issue and then have everyone create an issue in our repo for something they noticed or an idea they had).
• Hyperlink terminology to definition in glossary section (at least for the first time each term is used)
• Expand to 2.5 hours (with break) to incorporate content on repo types?

start the glossary section

this can be an ad-hoc issue to collect items to put into the glossary and committed to the main branch as needed.

starting list of random things!

• repo
• remote
• git flow
• sub-repo
• issue
• PR
• commit
• markdown
• github flavored-markdown (GFM)
• branch
• squashed commits
• commit hash (nickname for the git commit SHA-1 checksum value)

fix a typo in the first line of section 2.5.1

define forking in review chapter

since github PRs are primarily valuable for Open Source projects that require forking, we should describe that in ch 2.

collaborating chapter (4) - engaging section

Write the section in the "collaboration" chapter describing how to use pull requests to add to features of an existing project, either external or internal to your group.

please review the following as source material for this section , which may cover the bulk of what we want to cover, and the aspect of the course is to simplify and walk people through the concepts here.

https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project

add: how to checkout a remote branch?

this could be important for the 2nd workshop

to pull and work with an existing remote branch, you have use git fetch and thengit checkout

this Stack overflow post has lots of great info on that: https://stackoverflow.com/questions/1783405/how-do-i-check-out-a-remote-git-branch

write ch2 github workflow

basic edit workflow (clone) -> checkout -> edit -> add/stage -> edit -> commit -> repeat -> (push)
add diagram like this one:

fix a typo on the first page!

Fold ch. 5 into ch. 3

Will need to re-align file names to conform to new chapter order.

Chapter 5 should have a link to the book?

https://github.com/IBEEM-MSU/ibeem-collaborative-coding

start ch 3

cover 3.1 - 3.6 in our outline Anatomy of a GitHub repository

-Types of repositories:

• Implications of repository type for re-use
• Directory structures
  • What to look for when using someone else's code
• Interaction of source scripts
• Package vs project structures

perhaps here is a good place to define the difference between a "github project" and a "git repository"

put the workshop announcement right in the book

add the announcement we sent over email in this book, perhaps as a page called 'workshop announcement' or 'abount'

sending emails via MSU mangles the URLs in links, and can be hard to share, so it would be great if the announcement for the workshop were on-line somewhere. We could put it in the readme or some other markdown that is on this github site but not in the book, but might as well put it in the book. The book from the Arctic Res. Center is a great example for how to do this.

write about remotes

following #7, describe what a remote is and how to work with them. In the current outline this is after the one on branching, but I think it should be moved to be just after talking about github ( since github is a remote) and move the section on branching so it doesn't break up that order.

• why use git
• git branching
• why use github
  • what is github
  • alternatives to github
  • git is a server, too
• using remotes
• what the fork
  • it's just a copy of clone that you don't update...not github specific...more later

outline of book chapters

create empty book chapters based on the outline we started in google doc https://docs.google.com/document/d/1783P4ABrgB0XfT3ZfbY-iZI0uPNlyam4DHZi0DMVRqs/edit

Book correction

Licensing chapter resources

the main goal of this chapter is to say that that one needs to check a codebase license before blindly using it or taking parts of it. Some license don't allow for that.

Resources describing licenses and how to choose one:

• "A dev’s guide to open source software licensing" by Gina Häußge, github.com https://github.com/readme/guides/open-source-licensing
• Chapter on licensing from the Software Carpentry git workshop: https://swcarpentry.github.io/git-novice/11-licensing.html

write ch 2 why use github section

write section 2.3 and follow by 2.4 alternatives. In the alternative section, include description of how git can act as a server but has no real website, which very few people actually do, but you may encounter on a large team - see https://git-scm.com/book/en/v2/Git-on-the-Server-Setting-Up-the-Server

get gh pages workflow working

use github actions and workflow to build the book in to the ghpages branch to serve the book.

we have a workflow file but it's not being triggered , perhaps because it's triggered by a push only and not a merge and we've only merged into main?

on:
  push:
     branches:
       - master

nope that's not the problem

https://stackoverflow.com/questions/1783405/how-do-i-check-out-a-remote-git-branch

https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#running-your-workflow-when-a-pull-request-merges

use renv for portability and for gh workflow

renv is widely used to add a list of requirements to install. the repo will then contain an renv.lock file with list of dependencies

the github workflow used for #12 leverages renv lockfile to know what packages to install when building the book.

even if in the end we come up with a solution for #12 that doesn't use renv , we should use it anyway.

add license

suggest adding https://creativecommons.org/licenses/by-sa/4.0/

CC BY-SA 4.0

Attribution-ShareAlike 4.0 International

• add license file
• add mention with icon in readme
• add mention of license with icon on title page of book

Flesh out outline

Move google docs outline into bookdown format in the repo.

proposed workshop re-org for focus and flow

As Kelly points out there is a bunch of overlap in the start of a chapter on git practice with git review (ch. 2) As I write descriptions of how to interpret Github / OSS culture, I feel it's important to describe the feature and "feature-in-practice" to get insight into how github 'works.'

I propose interleaving the 'review' of git features into a "git /github features in practice" in order to make the workshop more efficient and engaging, esp. for those already using git. this may be more challenging for those who have not completed a git workshop previously

I want to keep the following in mind:

1. hierarchy/framework [code/codebase] -> [git repository] -> [github repository]

that is, the code itself is independent of git, and github, and we need to carefully separate aspects of code from aspects of github. Self-evident to git users but confusing to beginners.

2. SW carpentries already does an excellent job introducing git and some parts of what we want to talk about, so let's reference that as much as possible ( https://swcarpentry.github.io/git-novice/ )

3. given all the awesome git introductory materials out there, finding our niche will be tough: what are the truly under-explained topics?

   • git command process are already described in carpentries git workshop, which does not cover github, also covered in pro git book in depth
   • how git commands work on github are covered github documenation
   • that leaves: how people actually use these things in a workflow; principles that help drive the workflows

Assuming that those existing introductions to git on-line are sufficient, and that the attendees have seen those already,I propose the following organization to this book/workshop:

---

Intro (15 min)

Intro

• orientation: point out existing sources of doc on git (carpentries, books like "happy git...", websites, etc)
• why use git and github? this is our staring point
• framework code->git -> github
• optional participant introductions, previous experiences
• ensure everyone has a github account

Seminar/Demo (65 min)

git/github in practice (25 mi)

• list of git features/ commands we are assuming familiarity with in a git vs. github comparison
• foreach {commits, issues, branches, forks & pull requests, rebase}:
  • (Kelly) define the term/feature: review of the feature, rely on previous workshops/existing doc (as written for ch2)
  • (Kellly) point to how github works with this, link to github images and docs
  • (Pat) describe important elements of this feature in practice: principles of using commits, how much code to put into a commit and why ( this helps to understand the language of OSS collaboration )
  • (Pat) outline a typical workflow for using the feature
    • this helps to understand the context of the culture of OSS collaboration
    • real world example

Anatomy of a codebase (15 min)

• common elements (cover licensing here in 1 sentence and a link)
• our taxonomy
• example codebases

Using that code in your work (10 minutes)

• clonsider the licenceing

Engaging with issues and PRs ( 15 mintues )

• demo of that for a README file (Pat/Beth's repo)
• demo of that with our own book

Hands-on (20-25 min)

** Exercise: work through a real PR** (20-25 mintues)

• introducing bookdown and Markdown
• ensure everyone has a github account
• exercise (as written in #27)
• optional, bug bounty, find a typo or other bug and create issues in our repo
• optional: download RStudio and create book to test it!

Conclusion (15 min)

• as written in #26

Appendices and Glossary

create conclusion chapter

Include link to post-workshop survey.
https://docs.google.com/forms/d/e/1FAIpQLSf0093WX5C4qSedb7YIfOqVxPFbG8KpQQxpAJZiuyBGLj1rQA/viewform?usp=sf_link

consider git configuration review in ch 2

git works best if it's configured to match github configuration ( username, email).

this is not essential but if there is time, in the intro or just before the exercise, review configuration, following the same steps from https://happygitwithr.com/hello-git

Fix title