alexslemonade / 2023-chop-training Goto Github PK

This issue tracks a lesson on tracking and planning work with GitHub. It will introduce GitHub issues and cover the following:

• What makes a "good" issue?
  • Small in scope
  • Contains enough context that someone else could conceivably carry out the work
  • It will eventually get assigned to someone
• Why are small issues good issues
  • Helps spread work across a team
  • May help avoid merge conflicts
  • Leads to pull requests that are more manageable to review
  • Small issues lead to small wins
• Using issue templates to help you write "good issues"
• A brief mention of sprint planning
  • ZenHub and GitHub Projects as tools that exist to help

To save some time during live demos, it would be helpful to write the some of actual code ahead of time for safe-keeping! This way we can directly copy/paste in during live demos. This will be only helpful for initial versions of scripts, i.e. not for modifying an already-existing script. We may want to break this up into multiple issues, but for now...

• git basics demo: Histogram script without optparse
  • Edit: Free check box since this was part of the pre-workshop setup 🙃
• working with branches demo: Filter to 2008 penguins
• working with branches demo: Filter to Adelie penguins
• working with branches demo: Count penguin species
• working with branches demo: Summarize mass across penguin species
• stacking demo: Function to perform regression and return tidy output
• stacking demo: Run regression and export tidy result
• stacking demo: Function to make scatterplot
• stacking demo: Run scatterplot function and export PNG

Of course, I promptly thought of this after we templatized the demo repo next door, but it's not too difficult to do that again if it might be better for re-use to add this content to .live-demo-content/. CC @jaclyn-taroni, thoughts?

This lesson on git workflows and when to use them will comprise slides and links to public AlexsLemonade repositories that use different git workflows. The workflows we'll cover are:

• Feature branch model (example: sc-data-integration)
• Git flow (possible examples: scpca-nf and scpca-docs; note these are kind of weird because development is not the default)
• Forking (example: OpenPBTA-analysis)

But we'll start by talking about base roles in GitHub organizations.

We'll need a demo repository to... demo things like working with multiple branches, diffs, stacked PRs, and leaving reviews. This issue is tracking creating that repository.

When setting up the repository, I selected a BSD 3-clause license. A CC-BY license might be more appropriate for most of the content, as we'll be writing a pretty limited amount of code. Our other training material uses a dual license.

This is tracking a lesson on working with branches in Git, emphasizing managing multiple branches. It will include a live demo and should cover:

• The concept of a feature branch (a slide or two may help here)
• git status and git stash
• Branch protections
• Merge conflicts, which we'll come back to in day 2

A final version of the schedule should include links to the slides in PDF form.

This will be a few slides on what review is and how it works on GitHub. It won't explain why code review is useful (we'll save that for later). It's intended to provide some context before discussing tracking and planning work, where we'll mention review.

After some discussion about merge conflict live demo (#32), the working with branches issues should be marginally tweaked; it will have no effect on the overall concepts we're teaching, just some small differences in what scripts to be writing. This PR in the demo repository is adding the actual issues that will be used AlexsLemonade/2023-chop-training-demo#15. After that PR is all set, the associated instructor notes will need to be updated in this repo to match.

This issue tracks a lesson on git concepts we'll build on for the rest of the workshop. Specifically, we should cover:

• How much should go into a single commit
  • Using git status and git diff as you go, before you commit
• Informative commit messages
• .gitignore
• .gitkeep (edit)
• (edit) show Blame view in github, for an scpca repo, to explain the concept of Blame view (demo)

ETA: Some of this will be slides, but there could be space for live demos with git diff, etc.

This issue is tracking a set of slides that give an overview of the following items on analytical code review:

• Why do we do it?
• How does it help?
• Picking a reviewer
• Why is it helpful to get PRs merged relatively quickly (e.g., to help avoid merge conflicts)

This set of slides will cover things that can help with facilitating review that are outside the scope of an individual author's responsibilities, for example:

• Specific examples of using GitHub Actions: code styling and spell check
• How to spot things to automate with GHA 🤖
• Pull request templates
  • Trick for multiple templates

This live demo will cover strategies for making unreasonable diffs more reasonable, such as the following:

• Stacking pull requests (demo)
  • Forking model mostly doesn't mix with stacked PRs (slide)
• Cherry-picking commits (demo)
• Checking out individual files (slide)

The scope of this issue also includes writing instructor notes for the live demo portions to be placed in instructor-notes.

The live demo on pull request review will demonstrate the following:

• Suggestions
• Inline comments
• Overall file comments
• Overall comments
• Comment, approve, or request changes

The scope of this issue also includes writing instructor notes for the live demo portions to be placed in instructor-notes.

These slides should cover:

• Basic information about the instructors
• Housekeeping items like how to use the Slack channel
• What we will cover
• What we won't cover
• Overview of the schedule

Currently this repo is set to private. Let's make it public, and at the same time ensure the repo README is sufficiently descriptive (same level as we might do for a "regular" training, eg - https://github.com/AlexsLemonade/2023-march-training/#readme).

From this comment and associated discussion: #31 (comment)

Currently, the merge conflict demo does teach how to resolve merge conflicts, but it does not provide a highly realistic example of a more realistic merge conflict one might actually encounter. We should consider updating the demo, for example in a way that a result TSV file is modified resulting in a merge conflict, which may require more than just "open a tool and click theirs or ours" to fix, much like life.

This issue tracks a set of slides on pull request reviewer responsibilities, such as the following:

• Giving constructive, empathetic feedback
• Explaining what you did to review the code (e.g., did you try to run it or read it?)
• Scope of the review depends on in-house criteria

For a cleaner teaching experience, we should use a separate account on our computers.

• For everyone, make sure Zoom is installed and screen share is working
• For @sjspielman, a few more steps are needed!
  • GitKraken is installed and repo is linked
  • VS Code is installed with any necessary extensions
  • git is configured w/ 1Password (which may also need to be installed!)
    • Note to self: only log into CCDL account, not family account!
  • (edit) R + RStudio are installed with packages tidyverse, rmarkdown, broom, glue, here, palmerpenguins,umap, but not patchwork
  • Make sure repo can be cloned, but delete any clone before workshop (re-clone as part of live demo)

This lesson will cover topics that are relevant to the time period between when a review is returned through getting the code merged, which includes the following:

• Responding to review
  • Tip: filing new issues from comments
• Dealing with merge conflicts (live demo)
  • VS Code
  • GitKraken
• Deleting your branch, especially if stacking

We need to get in an initial set up of the course website in docs/ before drafting a schedule (#18). We can use this as an example: https://github.com/AlexsLemonade/reproducible-research/tree/main/docs

This set of slides on PR review will cover what kinds of responsibilities are shared between the author and reviewer(s) of a PR and get into the following:

• Understanding the impact of merging the PR (i.e., applying different standards for a private script to be used once vs. user-facing documentation)
• Reviewer fit
• Keeping things moving (e.g., don't let the PR balloon in scope)

Create a draft schedule. I've included an outline below. We'll need to figure out where to put breaks.

Day 1

• Introduction to the workshop (#6)
• First ~2 hours will cover git principles that could be used on a solo project (#3, #4, #5)
• Git workflows and when to use them (#7)
• Brief intro to PR review (#8)
• Tracking and planning work with GitHub (#9)

Day 2

• Analytical code review overview (#10)
• Shared PR responsibilities (#11)
• Systems for facilitating review (#12)
• Pull request author responsibilities (#13 and #14)
• Pull request reviewer responsibilities (#15 and #16)
• Initial review through merging your PR (#17)

This issue is tracking a lesson on using a git repository as a "lab notebook." This will mostly be delivered via slides and will cover the following topics:

• Documentation also needs to be included in your repo. Managing the code with git is not sufficient.
• Writing and organizing your code with someone else in mind.
• Briefly: Issues can be used as a (light) project management tool.

See #4 (comment)

The git basics instructor notes will need to be slightly updated to match the final.final plan as described in the linked comment, and/or in any subsequent conversations in that issue.

This issue encompasses two small updates as seen in workshop...

• for the stacking instructor notes, add text that the part 1 PRs need to get merged to enable part 2
• for the pr review instructor notes, use "comment" instead of "changes requested" when leaving the review, probably

We should add a page with some background and/or tutorials on Git and GitHub. We may not want to include this in the navigation and instead just link from the website homepage.

This issue tracks a set of slides covering individual pull request author responsibilities, including the following:

• Explaining yourself
  • Providing enough context
  • Soliciting the review you want
  • Private checklists if the template is not sufficient
• Keeping the size reasonable
  • Rules of thumb for reasonable sizes
• Looking at the diff