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
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.
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/ )
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)
(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!
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:
[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.
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/ )
given all the awesome git introductory materials out there, finding our niche will be tough: what are the truly under-explained topics?
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
Seminar/Demo (65 min)
git/github in practice (25 mi)
foreach {commits, issues, branches, forks & pull requests, rebase}:
Anatomy of a codebase (15 min)
Using that code in your work (10 minutes)
Engaging with issues and PRs ( 15 mintues )
Hands-on (20-25 min)
Exercise: work through a real PR (20-25 mintues)
Conclusion (15 min)
Appendices and Glossary