rse-sheffield / git-github-zero-to-hero

Training materials for zero to hero training in version control through git, github and gitkraken

Version control through Git, GitHub & GitKraken Client for researchers

This repo contains the source code of the website of the Git & Github through GitKraken Client - From Zero to Hero! course.

Prepation for course:

Schedule events on Eventbrite

The first step is to schedule events on Eventbrite. All steps are detailed in the Scheduling courses with Eventbrite GitHub Issue template.

Scheduling emails

More than 2 weeks prior to each session, a few emails need to be scheduled and the blackboard session created. All steps are detailed in the Schedule emails for next session GitHub Issue template. One issue should be opened per session and the tasks completed.

Preparing the materials

To prepare for each session, materials created during the previous session need to be cleared or deleted. All steps are detailed in the Prepare materials for next session GitHub Issue template. Each instructor (lead and support) should open an individual issue and complete the instructions.

Onboarding new instructors

Similarly, there is a GitHub Issue template for Setting up new Lead Instructors. Complete instructions to ensure new Instructors have all required software and materials downloaded, installed and functional.

Resources

The resources folder contains useful resources for teaching:

• bb_comms.png: Screenshot to demonstrate setting your status in blackboard collaborate. Upload to session and use in the introduction to make sure all participants can give feedback using status when asked questions.

---

It is powered by Hugo and the following themes:

• Hugo theme learn
• Hugo theme reveal-hugo

Slides for each section are listed in the menu and opened in a new tab (thanks to a custom menu layout, compared to the original Hugo learn theme).

Some Markdown content is generated with R Markdown, using hugodown.

The website is deployed by Netlify.

Why these tools?

Why use Hugo for both the website and slidedecks, and not, say Hugo+hugodown for pages and xaringan for slides? This way the source of slides is html produced by Hugo from Markdown content. It allows me to use:

• downlit syntax highlighting for slides created from R Markdown with hugodown output format;
• Chroma syntax highlighting for other languages;
• emojis! :grin: works in slides;
• Shortcodes in slides, should I choose to.

Also, because slides are in the content, they are indexed by the Hugo learn theme so searchable!

Credits

The workshop materials website template is based on the hugo-theme-learn, reveal-hugo Hugo themes and further work and configuration by Maëlle Salmon for her course site on Scientific blogging with R Markdown.

git-github-zero-to-hero's Issues

Add notes to video tutorial links

For instance, the video tutorial for installing git on windows (from SWC) also details installation of nano using a SWC installer, which isn't required for this workshop.

In fact, is gitbash even required for gitkraken? Even if it's not I think it's nice to leave participants with git installed on whatever OS.

@annakrystalli @ns-rse @bobturneruk happy to discuss.

Schedule emails for session on 10th March 2022

Emails need to be scheduled via eventbrite ahead of each session.

Emails

There are up to 4 emails that need to be scheduled for this course. There are parameterised .Rmd templates in the emails/ directory to generate the contents of these emails.

• 2 weeks prior to the event - attendance_reminder_email.Rmd: an attendance reminder to encourage participants who cannot attend anymore to cancel

• 1 week prior to the event - setup_email.Rmd: a reminder of the setup instructors as well as information about the session platform and joining link

• On the morning of the event - joining_reminder_email.Rmd: A reminder of the joining link

• Day after the event - feedback_survey_email.Rmd a request to complete a survey.
  The parameters required are:

• lead_instructor: name of the lead instructor

• session_joining_link: link to the blackboard collaborate room (if teaching on-line)

• event_date: the date of the session in ISO format (YYYY-MM-DD)

• event_start_time: defaults to "10:00"

• lunch_time: defaults to "13:00"

• prefilled_survey_link: the unchanging part of the survey link containing the identifier of the date of course question to be pre-populated with the event_date parameter.

To use these, open each .Rmd, edit parameters in the YAML header and knit to render to html. The html content should then be copied (from the viewer or the generated HTML document) and pasted into the eventbrite message content box.

Make sure to send a test message to yourself and to check each link prior to finalising the email.

Blackboard Collaborate Session

• Go to Blackboard Collaborate, logging in via MUSE,
• Under Organisations open COM - Research Software Engineering,
• Select Create Session and fill in the details as follows:
  • Session Name: git & GitHub through GitKraken - from Zero to Hero!
  • Guest Access: ✔️
  • Make sure that Guest role is set to participant
  • Set the start and end dates and times suitable for the session, add 30 mins to 1hr extra onto the scheduled end time.
  • Early entry: 15 minutes before start time.
• Click create, this will create the session link, make a note of this for the emails.

Checklist

Complete as necessary (dependent on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• attendance reminder email
• set up blackboard session
• setup email
• joining email
• feedback email

Once all tasks are complete, please close issue.

Already done, just completing this for our records.

Improve clarity of emails/description etc

We may need a bit more clarity on things like location/remote

Feedback from 2022-01-20

Instructor:

• Issue with accepting (finding) GitHub invitations: https://github.community/t/where-do-i-see-all-incoming-invitations-collaborator/661/4.
  Solution: You can also see the invite if you know which repo you were invited to:
  https://github.com/username/reponame/invitations <- NEEDS TESTING
• Issues with GitKraken on UBUNTU:
  • installation issue: Solution add note to setup instructions about testing UBUNTU especially and getting in touch if they have issues before course.
  • Appearance issue
• Expand by half hr to give more breathing space to afternoon.
• When demoing executing instructions in issue, make single commit to also demonstrate committing changes to multiple files

Prepare materials for session on 10/5/22 for @davidwilby

All instructors (lead and support) need to do some preparation (especially to repos in their own accounts) if they have created materials during a previously run course. Lead instructor has some extra prep steps.

Complete as necessary (dependant on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• Delete git-lesson repo from instructor's GitHub account. Delete local copy if you want to use same location for demo.
• Delete collaborative_github_exercise fork repo FROM INSTRUCTOR'S ACCOUNT ONLY. Do NOT delete the RSE-Sheffield original repo. Delete local copy (of fork!) if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear previously submitted parameter files from params/ folder in RSE-Sheffield/collaborative_github_exercise repo. DO NOT DELETE params_tmpl.R. Synch local and remote repos.
• Delete python-calculator repo from instructor's account. Delete local copy if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear collaborative team formation googledoc

Once all tasks are complete, please close issue.

Template for Eventbrite setup

Create a template for setting up Eventbrite.

Prepare materials for session on 2022-10-03 to 2022-10-04 for ns-rse

All instructors (lead and support) need to do some preparation (especially to repos in their own accounts) if they have created materials during a previously run course. Lead instructor has some extra prep steps.

Complete as necessary (dependant on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• Delete git-lesson repo from instructor's GitHub account. Delete local copy if you want to use same location for demo.
• Delete collaborative_github_exercise fork repo FROM INSTRUCTOR'S ACCOUNT ONLY. Do NOT delete the RSE-Sheffield original repo. Delete local copy (of fork!) if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear previously submitted parameter files from params/ folder in RSE-Sheffield/collaborative_github_exercise repo. DO NOT DELETE params_tmpl.R. Synch local and remote repos.
• Delete python-calculator repo from instructor's account. Delete local copy if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear collaborative team formation googledoc

Once all tasks are complete, please close issue.

Add a license to the repository

Realised delivering the course this morning that the repository itself is missing a license.

We should therefore add a license to the repository, open to which license to use and input welcome.

Prepare materials for session on 2/8/22 for David

All instructors (lead and support) need to do some preparation (especially to repos in their own accounts) if they have created materials during a previously run course. Lead instructor has some extra prep steps.

Complete as necessary (dependant on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• Delete git-lesson repo from instructor's GitHub account. Delete local copy if you want to use same location for demo.
• Delete collaborative_github_exercise fork repo FROM INSTRUCTOR'S ACCOUNT ONLY. Do NOT delete the RSE-Sheffield original repo. Delete local copy (of fork!) if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear previously submitted parameter files from params/ folder in RSE-Sheffield/collaborative_github_exercise repo. DO NOT DELETE params_tmpl.R. Synch local and remote repos.
• Delete python-calculator repo from instructor's account. Delete local copy if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear collaborative team formation googledoc

Once all tasks are complete, please close issue.

Prepare materials for session on 2022-10-31 to 2022-11-01 for Neil & Bob

All instructors (lead and support) need to do some preparation (especially to repos in their own accounts) if they have created materials during a previously run course. Lead instructor has some extra prep steps.

Complete as necessary (dependant on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• Delete git-lesson repo from instructor's GitHub account. Delete local copy if you want to use same location for demo.
• Delete collaborative_github_exercise fork repo FROM INSTRUCTOR'S ACCOUNT ONLY. Do NOT delete the RSE-Sheffield original repo. Delete local copy (of fork!) if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear previously submitted parameter files from params/ folder in RSE-Sheffield/collaborative_github_exercise repo. DO NOT DELETE params_tmpl.R. Synch local and remote repos.
• Delete python-calculator repo from instructor's account. Delete local copy if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear collaborative team formation googledoc

Once all tasks are complete, please close issue.

Prepare materials for session on 2022-10-3 for Bob Turner

All instructors (lead and support) need to do some preparation (especially to repos in their own accounts) if they have created materials during a previously run course. Lead instructor has some extra prep steps.

Complete as necessary (dependant on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• Delete git-lesson repo from instructor's GitHub account. Delete local copy if you want to use same location for demo.
• Delete collaborative_github_exercise fork repo FROM INSTRUCTOR'S ACCOUNT ONLY. Do NOT delete the RSE-Sheffield original repo. Delete local copy (of fork!) if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear previously submitted parameter files from params/ folder in RSE-Sheffield/collaborative_github_exercise repo. DO NOT DELETE params_tmpl.R. Synch local and remote repos.
• Delete python-calculator repo from instructor's account. Delete local copy if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear collaborative team formation googledoc

Once all tasks are complete, please close issue.

Setup new instructor

Documentation for most setup instructions is available in the course material setup chapter.

• Install git
• Create GitHub account
• Install GitKraken
• Sign-in to GitKraken with GitHub account.
• Ensure SSH keypair for accessing GitHub is configured in GitKraken.
• Clone collaborative-github repo from RSE-Sheffield account.
• Ensure you have admin access to RSE-Sheffiel/collaborative-github
• Run index.Rmd to install dependencies.

Prepare materials for session on 2022-06-07 for Bob

All instructors (lead and support) need to do some preparation (especially to repos in their own accounts) if they have created materials during a previously run course. Lead instructor has some extra prep steps.

Complete as necessary (dependant on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• Delete git-lesson repo from instructor's GitHub account. Delete local copy if you want to use same location for demo.
• Delete collaborative_github_exercise fork repo FROM INSTRUCTOR'S ACCOUNT ONLY. Do NOT delete the RSE-Sheffield original repo. Delete local copy (of fork!) if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear previously submitted parameter files from params/ folder in RSE-Sheffield/collaborative_github_exercise repo. DO NOT DELETE params_tmpl.R. Synch local and remote repos.
• Delete python-calculator repo from instructor's account. Delete local copy if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear collaborative team formation googledoc

Once all tasks are complete, please close issue.

Prepare materials for session on 2021-11-09 for AK

All instructors (lead and secondary) need to do some preparation (especially to repos in theirs accounts) if they have created materials during a previously run course. Lead instructor has some extra prep steps.

Complete as necessary (dependant in what has been created in the past). Tick off tasks as they are completed or if they are not required.

• Delete git-lesson repo from instructor's GitHub account. Delete local copy if you want to use same location for demo.
• Delete collaborative-github-exercise fork repo from instructor's account. Delete local copy (of fork!) if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear previously submitted parameter files from params/ folder in RSE-Sheffield/collaborative-github-exercise repo. DO NOT DELETE params_tmpl.R. Synch local and remote repos.
• Delete python-calculator repo from instructor's account. Delete local copy if you want to use same location for demo.

Prepare materials for session on 2022-04-12 for @bobturneruk

All instructors (lead and support) need to do some preparation (especially to repos in their own accounts) if they have created materials during a previously run course. Lead instructor has some extra prep steps.

Complete as necessary (dependant on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• optional Delete git-lesson repo from instructor's GitHub account. Delete local copy if you want to use same location for demo.
• optional Delete collaborative_github_exercise fork repo FROM INSTRUCTOR'S ACCOUNT ONLY. Do NOT delete the RSE-Sheffield original repo. Delete local copy (of fork!) if you want to use same location for demo.
• @bobturneruk Delete python-calculator repo from instructor's account. Delete local copy if you want to use same location for demo.

Once all tasks are complete, please close issue.

Prepare materials for session on 2022-02-01 for @annakrystalli

All instructors (lead and support) need to do some preparation (especially to repos in their own accounts) if they have created materials during a previously run course. Lead instructor has some extra prep steps.

Complete as necessary (dependant on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• Delete git-lesson repo from instructor's GitHub account. Delete local copy if you want to use same location for demo.
• Delete collaborative_github_exercise fork repo FROM INSTRUCTOR'S ACCOUNT ONLY. Do NOT delete the RSE-Sheffield original repo. Delete local copy (of fork!) if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear previously submitted parameter files from params/ folder in RSE-Sheffield/collaborative_github_exercise repo. DO NOT DELETE params_tmpl.R. Synch local and remote repos.
• Delete python-calculator repo from instructor's account. Delete local copy if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear collaborative team formation googledoc

Once all tasks are complete, please close issue.

Add some recap materials before section 4

Since the course is frequently being delivered as a 2 half day format, we thought that it would be handy to have some (optional) recap materials before section 4 (advanced collaboration) since this is often where the second day begins.

Create an FAQ in course materials

There are some FAQs in the wiki but over the last few runs we have collected various other questions (see page FAQ notes made by @ns-rse during the courses).

These should all be combined into a single FAQ. At the same time we can address #20.

Prepare materials for session on 2021-12-09

All instructors (lead and secondary) need to do some preparation (especially to repos in theirs accounts) if they have created materials during a previously run course. Lead instructor has some extra prep steps.

Complete as necessary (dependant in what has been created in the past). Tick off tasks as they are completed or if they are not required.

• Delete git-lesson repo from instructor's GitHub account. Delete local copy if you want to use same location for demo.
• Delete collaborative_github_exercise fork repo from instructor's account. Delete local copy (of fork!) if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear previously submitted parameter files from params/ folder in RSE-Sheffield/collaborative_github_exercise repo. DO NOT DELETE params_tmpl.R. Synch local and remote repos.
• Delete python-calculator repo from instructor's account. Delete local copy if you want to use same location for demo.

Feedback from 2021-12-09

• Recommend two screen setup
• Add clearing collaborative notepad to issue

Schedule emails for session on 2022-10-03/04 for Neil Shephard

Emails need to be scheduled via eventbrite ahead of each session.

Emails

There are up to 4 emails that need to be scheduled for this course. There are parameterised .Rmd templates in the emails/ directory to generate the contents of these emails.

• 2 weeks prior to the event - attendance_reminder_email.Rmd: an attendance reminder to encourage participants who cannot attend anymore to cancel
• 1 week prior to the event - setup_email.Rmd: a reminder of the setup instructors as well as information about the session platform and joining link
• 3 days prior to the event - setup_email.Rmd: a reminder of the setup instructors as well as information about the session platform and joining link
• On the morning of the event - joining_reminder_email.Rmd: A reminder of the joining link
• Day after the event - feedback_survey_email.Rmd a request to complete a survey.

The parameters required are:

• lead_instructor: name of the lead instructor
• session_joining_link: link to the blackboard collaborate room (if teaching on-line)
• event_date: the date of the session in ISO format (YYYY-MM-DD)
• event_start_time: defaults to "10:00"
• lunch_time: defaults to "13:00"
• prefilled_survey_link: the unchanging part of the survey link containing the identifier of the date of course question to be pre-populated with the event_date parameter.

To use these, open each .Rmd, edit parameters in the YAML header and knit to render to html. The html content should then be copied (from the viewer or the generated HTML document) and pasted into the eventbrite message content box.

Make sure to send a test message to yourself and to check each link prior to finalising the email.

Blackboard Collaborate Session

• Go to Blackboard Collaborate, logging in via MUSE,
• Under Organisations open COM - Research Software Engineering,
• Select Create Session and fill in the details as follows:
  • Session Name: git & GitHub through GitKraken - from Zero to Hero!
  • Guest Access: ✔️
  • Make sure that Guest role is set to participant
  • Set the start and end dates and times suitable for the session, add 30 mins to 1hr extra onto the scheduled end time.
  • Early entry: 15 minutes before start time.
• Click create, this will create the session link, make a note of this for the emails.

Checklist

Complete as necessary (dependent on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• Announce to waiting list.
• Announce on RSE mailing list.
• Announce more widely to University of Sheffield announcements.
• attendance reminder email.
• set up blackboard session.
• setup email (1 week).
• setup email (3 days).
• joining email
• feedback email

Once all tasks are complete, please close issue.

Prepare materials for session on Scharr 2022-10-06 for Bob

All instructors (lead and support) need to do some preparation (especially to repos in their own accounts) if they have created materials during a previously run course. Lead instructor has some extra prep steps.

Complete as necessary (dependant on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• Delete git-lesson repo from instructor's GitHub account. Delete local copy if you want to use same location for demo.
• Delete collaborative_github_exercise fork repo FROM INSTRUCTOR'S ACCOUNT ONLY. Do NOT delete the RSE-Sheffield original repo. Delete local copy (of fork!) if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear previously submitted parameter files from params/ folder in RSE-Sheffield/collaborative_github_exercise repo. DO NOT DELETE params_tmpl.R. Synch local and remote repos.
• Delete python-calculator repo from instructor's account. Delete local copy if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear collaborative team formation googledoc

Once all tasks are complete, please close issue.

Prepare materials for session on 2022-04-12 for @davidwilby

All instructors (lead and support) need to do some preparation (especially to repos in their own accounts) if they have created materials during a previously run course. Lead instructor has some extra prep steps.

Complete as necessary (dependant on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• Delete git-lesson repo from instructor's GitHub account. Delete local copy if you want to use same location for demo.
• Delete collaborative_github_exercise fork repo FROM INSTRUCTOR'S ACCOUNT ONLY. Do NOT delete the RSE-Sheffield original repo. Delete local copy (of fork!) if you want to use same location for demo.
• @davidwilby Clear previously submitted parameter files from params/ folder in RSE-Sheffield/collaborative_github_exercise repo. DO NOT DELETE params_tmpl.R. Synch local and remote repos.
• Delete python-calculator repo from instructor's account. Delete local copy if you want to use same location for demo.
• @davidwilby Clear collaborative team formation googledoc

Once all tasks are complete, please close issue.

Prepare materials for session on 2022-10-03/04 for Neil Shephard

All instructors (lead and support) need to do some preparation (especially to repos in their own accounts) if they have created materials during a previously run course. Lead instructor has some extra prep steps.

Complete as necessary (dependant on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• Delete git-lesson repo from instructor's GitHub account. Delete local copy if you want to use same location for demo.
• Delete collaborative_github_exercise fork repo FROM INSTRUCTOR'S ACCOUNT ONLY. Do NOT delete the RSE-Sheffield original repo. Delete local copy (of fork!) if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear previously submitted parameter files from params/ folder in RSE-Sheffield/collaborative_github_exercise repo. DO NOT DELETE params_tmpl.R. Synch local and remote repos.
• Delete python-calculator repo from instructor's account. Delete local copy if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear collaborative team formation googledoc

Once all tasks are complete, please close issue.

Prepare materials for session on Scharr 2022-10-06 for Neil

All instructors (lead and support) need to do some preparation (especially to repos in their own accounts) if they have created materials during a previously run course. Lead instructor has some extra prep steps.

Complete as necessary (dependant on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• Delete git-lesson repo from instructor's GitHub account. Delete local copy if you want to use same location for demo.
• Delete collaborative_github_exercise fork repo FROM INSTRUCTOR'S ACCOUNT ONLY. Do NOT delete the RSE-Sheffield original repo. Delete local copy (of fork!) if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear previously submitted parameter files from params/ folder in RSE-Sheffield/collaborative_github_exercise repo. DO NOT DELETE params_tmpl.R. Synch local and remote repos.
• Delete python-calculator repo from instructor's account. Delete local copy if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear collaborative team formation googledoc

Once all tasks are complete, please close issue.

Prepare materials for session on 2022-10-03 to 2022-10-04 for Bob Turner

All instructors (lead and support) need to do some preparation (especially to repos in their own accounts) if they have created materials during a previously run course. Lead instructor has some extra prep steps.

Complete as necessary (dependant on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• Delete git-lesson repo from instructor's GitHub account. Delete local copy if you want to use same location for demo.
• Delete collaborative_github_exercise fork repo FROM INSTRUCTOR'S ACCOUNT ONLY. Do NOT delete the RSE-Sheffield original repo. Delete local copy (of fork!) if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear previously submitted parameter files from params/ folder in RSE-Sheffield/collaborative_github_exercise repo. DO NOT DELETE params_tmpl.R. Synch local and remote repos.
• Delete python-calculator repo from instructor's account. Delete local copy if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear collaborative team formation googledoc

Once all tasks are complete, please close issue.

Prepare materials for session on 1st Feb 2022 for @davidwilby

All instructors (lead and support) need to do some preparation (especially to repos in their own accounts) if they have created materials during a previously run course. Lead instructor has some extra prep steps.

Complete as necessary (dependant on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• Delete git-lesson repo from instructor's GitHub account. Delete local copy if you want to use same location for demo.
• Delete collaborative_github_exercise fork repo FROM INSTRUCTOR'S ACCOUNT ONLY. Do NOT delete the RSE-Sheffield original repo. Delete local copy (of fork!) if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear previously submitted parameter files from params/ folder in RSE-Sheffield/collaborative_github_exercise repo. DO NOT DELETE params_tmpl.R. Synch local and remote repos.
• Delete python-calculator repo from instructor's account. Delete local copy if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear collaborative team formation googledoc

Once all tasks are complete, please close issue.

Setup New Lead instructor @davidwilby

Documentation for most setup instructions is available in the course material setup chapter.

• Install git
• Install R & RStudio
• Create GitHub account
• Install GitKraken
• Sign-in to GitKraken with GitHub account.
• Ensure SSH keypair for accessing GitHub is configured in GitKraken.
• Clone RSE-Sheffield/collaborative_github_exercise repo. Clone it to somewhere where you won't get it mixed up with the fork you will clone during teaching.
• Ensure you have admin access to RSE-Sheffield/collaborative_github_exercise
• Open RSE-Sheffield/collaborative_github_exercise project in Rstudio
• Run renv::restore() to install dependencies.
• Test that you can knit plot_trait_evolution.Rmd succesfully. If it succeeds, it's fine to revert the resulting plot_trait_evolution.html to it's previous state instead of committing the changes. However, make sure they are cleared in the git tab one way or the other so as not to confuse the demo.

Adding git graphs to the materials?

Feel free to disagree! (also could move this to GH discussions if we think it would be beneficial)

I think that a couple of additional visuals would help me personally when delivering this training to illustrate some of the concepts around commits and branches.

In the advanced collaboration section, I wonder if we could do with a diagram that shows branching a bit more visually.

The current diagram we have here:

does a good job illustrating the flow IMO, but doesn't visually show the branching concept.

We could add something like the following to show branching a bit more clearly.

gitGraph
    commit
    commit
    commit
    commit
    commit
    branch feature
    checkout feature
    commit
    commit
    checkout main

Loading

(aside: check out this sweet mermaid gitgraph feature)

Which could then be extended to show the pull request and merge steps, e.g.

gitGraph
    commit
    commit
    commit
    commit
    commit
    branch feature
    checkout feature
    commit
    commit
    checkout main
    merge feature

Loading

I'd be interested to know others' thoughts on this.

Feedback from 2022-02-01

1. Gitkraken Client has a 7-day trial period - is this waived for github pro/education users?
2. Issue with user having Block command line pushes that expose my email enabled - possible fix here: https://stackoverflow.com/questions/43378060/meaning-of-the-github-message-push-declined-due-to-email-privacy-restrictions - @davidwilby will investigate. (Probably unlikely to be a frequent problem, but I think it's reasonable for a user to have this option enabled on github)
3. Possibly worth making the afternoon session even longer, still ran pretty close to the time available, would have been good to have a bit longer.
4. Include in materials a clearer indication that the team owners should create all the issues at the same time and that the team members should follow along with their particular issue instructions, I got a little bit confused and forgot to make this clear, which meant that not everyone had an issue assigned to follow along with Bob's demo. This is more just to help me and my feeble brain.

Glossary?

Would it be worth adding a glossary page to the materials for some of the new terms such as:

• repository
• clone
• fork
• origin/upstream
• local
  ?

Schedule emails for session on 2022-04-12 for @davidwilby

Emails need to be scheduled via eventbrite ahead of each session.

Emails

There are up to 4 emails that need to be scheduled for this course. There are parameterised .Rmd templates in the emails/ directory to generate the contents of these emails.

• 2 weeks prior to the event - attendance_reminder_email.Rmd: an attendance reminder to encourage participants who cannot attend anymore to cancel

• 1 week prior to the event - setup_email.Rmd: a reminder of the setup instructors as well as information about the session platform and joining link

• On the morning of the event - joining_reminder_email.Rmd: A reminder of the joining link

• Day after the event - feedback_survey_email.Rmd a request to complete a survey.
  The parameters required are:

• lead_instructor: name of the lead instructor

• session_joining_link: link to the blackboard collaborate room (if teaching on-line)

• event_date: the date of the session in ISO format (YYYY-MM-DD)

• event_start_time: defaults to "10:00"

• lunch_time: defaults to "13:00"

• prefilled_survey_link: the unchanging part of the survey link containing the identifier of the date of course question to be pre-populated with the event_date parameter.

To use these, open each .Rmd, edit parameters in the YAML header and knit to render to html. The html content should then be copied (from the viewer or the generated HTML document) and pasted into the eventbrite message content box.

Make sure to send a test message to yourself and to check each link prior to finalising the email.

Blackboard Collaborate Session

• Go to Blackboard Collaborate, logging in via MUSE,
• Under Organisations open COM - Research Software Engineering,
• Select Create Session and fill in the details as follows:
  • Session Name: git & GitHub through GitKraken - from Zero to Hero!
  • Guest Access: ✔️
  • Make sure that Guest role is set to participant
  • Set the start and end dates and times suitable for the session, add 30 mins to 1hr extra onto the scheduled end time.
  • Early entry: 15 minutes before start time.
• Click create, this will create the session link, make a note of this for the emails.

Checklist

Complete as necessary (dependent on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• attendance reminder email
• set up blackboard session
• setup email
• joining email
• feedback email

Once all tasks are complete, please close issue.

Prepare materials for session on 6/6/22 for davidwilby

All instructors (lead and support) need to do some preparation (especially to repos in their own accounts) if they have created materials during a previously run course. Lead instructor has some extra prep steps.

Complete as necessary (dependant on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• Delete git-lesson repo from instructor's GitHub account. Delete local copy if you want to use same location for demo.
• Delete collaborative_github_exercise fork repo FROM INSTRUCTOR'S ACCOUNT ONLY. Do NOT delete the RSE-Sheffield original repo. Delete local copy (of fork!) if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear previously submitted parameter files from params/ folder in RSE-Sheffield/collaborative_github_exercise repo. DO NOT DELETE params_tmpl.R. Synch local and remote repos.
• Delete python-calculator repo from instructor's account. Delete local copy if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear collaborative team formation googledoc

Once all tasks are complete, please close issue.

Add the blackboard image to the course materials

In resources/ we have a blackboard screenshot, we should think about adding this into the course materials somewhere to make it easier for presenting. Though probably in some extra materials, not in the main stuff.

Schedule emails for session on 10/5/22 for David

Emails need to be scheduled via eventbrite ahead of each session.

Emails

There are up to 4 emails that need to be scheduled for this course. There are parameterised .Rmd templates in the emails/ directory to generate the contents of these emails.

• 2 weeks prior to the event - attendance_reminder_email.Rmd: an attendance reminder to encourage participants who cannot attend anymore to cancel

• 1 week prior to the event - setup_email.Rmd: a reminder of the setup instructors as well as information about the session platform and joining link

• On the morning of the event - joining_reminder_email.Rmd: A reminder of the joining link

• Day after the event - feedback_survey_email.Rmd a request to complete a survey.
  The parameters required are:

• lead_instructor: name of the lead instructor

• session_joining_link: link to the blackboard collaborate room (if teaching on-line)

• event_date: the date of the session in ISO format (YYYY-MM-DD)

• event_start_time: defaults to "10:00"

• lunch_time: defaults to "13:00"

• prefilled_survey_link: the unchanging part of the survey link containing the identifier of the date of course question to be pre-populated with the event_date parameter.

To use these, open each .Rmd, edit parameters in the YAML header and knit to render to html. The html content should then be copied (from the viewer or the generated HTML document) and pasted into the eventbrite message content box.

Make sure to send a test message to yourself and to check each link prior to finalising the email.

Blackboard Collaborate Session

• Go to Blackboard Collaborate, logging in via MUSE,
• Under Organisations open COM - Research Software Engineering,
• Select Create Session and fill in the details as follows:
  • Session Name: git & GitHub through GitKraken - from Zero to Hero!
  • Guest Access: ✔️
  • Make sure that Guest role is set to participant
  • Set the start and end dates and times suitable for the session, add 30 mins to 1hr extra onto the scheduled end time.
  • Early entry: 15 minutes before start time.
• Click create, this will create the session link, make a note of this for the emails.

Checklist

Complete as necessary (dependent on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• attendance reminder email
• set up blackboard session
• setup email
• joining email
• feedback email

Once all tasks are complete, please close issue.

Prepare for next session

• Delete git-lesson repo from instructor's account.
• Delete collaborative-github repo from instructor's account.
• Clear previously submitted parameter files from params folder in RSE-Sheffield/collaborative-github repo. DO NOT DELETE params-tmpl.R
• Delete python-calculator repo from instructor's account.

Setup New Lead instructor Neil Shephard

Documentation for most setup instructions is available in the course material setup chapter.

• Install git
• Install R & RStudio
• Create GitHub account
• Install GitKraken
• Sign-in to GitKraken with GitHub account.
• Ensure SSH keypair for accessing GitHub is configured in GitKraken.
• Clone RSE-Sheffield/collaborative_github_exercise repo. Clone it to somewhere where you won't get it mixed up with the fork you will clone during teaching.
• Ensure you have admin access to RSE-Sheffield/collaborative_github_exercise
• Open RSE-Sheffield/collaborative_github_exercise project in Rstudio
• Run renv::restore() to install dependencies.
• Test that you can knit plot_trait_evolution.Rmd succesfully. If it succeeds, it's fine to revert the resulting plot_trait_evolution.html to it's previous state instead of committing the changes. However, make sure they are cleared in the git tab one way or the other so as not to confuse the demo.

debrief from 2022-04-12

• Just use gitkraken text editor to avoid confusion
• Can we simplify the deliberate errors to make them less pythonic and reduce the conflicts?
• Extra 30 mins in afternoon was good and morning session worked well with 30 mins less.
• Perhaps go through contirbutor/team member section more slowly?
• Git for windows is specified in the setup instructions but is not required, don't need to install git at all to use gitkraken.
• schedule a course that doesn't overlap school pickup times
• ask Matt to help out on some future courses

GitHub have completely removed the setting for pages themes

In setting a pages theme, there used to be a convenient dialog for selecting one but now you have to manually add a _config.yml file.
Would suggest possibly removing the theme section from the exercise for the time-being.

Prepare materials for session on 2022-01-20 for @bobturneruk

All instructors (lead and support) need to do some preparation (especially to repos in their own accounts) if they have created materials during a previously run course. Lead instructor has some extra prep steps.

Complete as necessary (dependant in what has been created in the past). Tick off tasks as they are completed or if they are not required.

• Delete git-lesson repo from instructor's GitHub account. Delete local copy if you want to use same location for demo.
• Delete collaborative_github_exercise fork repo FROM INSTRUCTOR'S ACCOUNT ONLY. Do NOT delete the RSE-Sheffield original repo. Delete local copy (of fork!) if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear previously submitted parameter files from params/ folder in RSE-Sheffield/collaborative_github_exercise repo. DO NOT DELETE params_tmpl.R. Synch local and remote repos.
• Delete python-calculator repo from instructor's account. Delete local copy if you want to use same location for demo.
• Clear collaborative team formation googledoc

Prepare materials for session on 2022-01-20 for @annakrystalli

All instructors (lead and support) need to do some preparation (especially to repos in their own accounts) if they have created materials during a previously run course. Lead instructor has some extra prep steps.

Complete as necessary (dependant in what has been created in the past). Tick off tasks as they are completed or if they are not required.

• Delete git-lesson repo from instructor's GitHub account. Delete local copy if you want to use same location for demo.
• Delete collaborative_github_exercise fork repo FROM INSTRUCTOR'S ACCOUNT ONLY. Do NOT delete the RSE-Sheffield original repo. Delete local copy (of fork!) if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear previously submitted parameter files from params/ folder in RSE-Sheffield/collaborative_github_exercise repo. DO NOT DELETE params_tmpl.R. Synch local and remote repos.
• Delete python-calculator repo from instructor's account. Delete local copy if you want to use same location for demo.
• Clear collaborative team formation googledoc

Schedule emails for session on 6/7th June 2022

Emails need to be scheduled via eventbrite ahead of each session.

Emails

There are up to 4 emails that need to be scheduled for this course. There are parameterised .Rmd templates in the emails/ directory to generate the contents of these emails.

• 2 weeks prior to the event - attendance_reminder_email.Rmd: an attendance reminder to encourage participants who cannot attend anymore to cancel

• 1 week prior to the event - setup_email.Rmd: a reminder of the setup instructors as well as information about the session platform and joining link

• On the morning of the event - joining_reminder_email.Rmd: A reminder of the joining link

• Day after the event - feedback_survey_email.Rmd a request to complete a survey.
  The parameters required are:

• lead_instructor: name of the lead instructor

• session_joining_link: link to the blackboard collaborate room (if teaching on-line)

• event_date: the date of the session in ISO format (YYYY-MM-DD)

• event_start_time: defaults to "10:00"

• lunch_time: defaults to "13:00"

• prefilled_survey_link: the unchanging part of the survey link containing the identifier of the date of course question to be pre-populated with the event_date parameter.

To use these, open each .Rmd, edit parameters in the YAML header and knit to render to html. The html content should then be copied (from the viewer or the generated HTML document) and pasted into the eventbrite message content box.

Make sure to send a test message to yourself and to check each link prior to finalising the email.

Blackboard Collaborate Session

• Go to Blackboard Collaborate, logging in via MUSE,
• Under Organisations open COM - Research Software Engineering,
• Select Create Session and fill in the details as follows:
  • Session Name: git & GitHub through GitKraken - from Zero to Hero!
  • Guest Access: ✔️
  • Make sure that Guest role is set to participant
  • Set the start and end dates and times suitable for the session, add 30 mins to 1hr extra onto the scheduled end time.
  • Early entry: 15 minutes before start time.
• Click create, this will create the session link, make a note of this for the emails.

Checklist

Complete as necessary (dependent on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• attendance reminder email
• set up blackboard session
• setup email
• joining email
• feedback email

Once all tasks are complete, please close issue.

Add some follow up guidance on how to go forward

I'd like these materials to be a useful resource beyond the course and to include some guidance on where to go from here.

I don't expect anyone else to do this, this issue is mainly to remind me and collect my thoughts, but if anyone wants to do any of this be my guest.

1. How to work alone.
2. How to work in a collaborative team.
3. How to bring my existing code under version control.
4. Good practice with git in general.

Schedule emails for session on 26/7/22 for David

Emails need to be scheduled via eventbrite ahead of each session.

Emails

There are up to 4 emails that need to be scheduled for this course. There are parameterised .Rmd templates in the emails/ directory to generate the contents of these emails.

• 2 weeks prior to the event - attendance_reminder_email.Rmd: an attendance reminder to encourage participants who cannot attend anymore to cancel

• 1 week prior to the event - setup_email.Rmd: a reminder of the setup instructors as well as information about the session platform and joining link

• On the morning of the event - joining_reminder_email.Rmd: A reminder of the joining link

• Day after the event - feedback_survey_email.Rmd a request to complete a survey.
  The parameters required are:

• lead_instructor: name of the lead instructor

• session_joining_link: link to the blackboard collaborate room (if teaching on-line)

• event_date: the date of the session in ISO format (YYYY-MM-DD)

• event_start_time: defaults to "10:00"

• lunch_time: defaults to "13:00"

• prefilled_survey_link: the unchanging part of the survey link containing the identifier of the date of course question to be pre-populated with the event_date parameter.

To use these, open each .Rmd, edit parameters in the YAML header and knit to render to html. The html content should then be copied (from the viewer or the generated HTML document) and pasted into the eventbrite message content box.

Make sure to send a test message to yourself and to check each link prior to finalising the email.

Blackboard Collaborate Session

• Go to Blackboard Collaborate, logging in via MUSE,
• Under Organisations open COM - Research Software Engineering,
• Select Create Session and fill in the details as follows:
  • Session Name: git & GitHub through GitKraken - from Zero to Hero!
  • Guest Access: ✔️
  • Make sure that Guest role is set to participant
  • Set the start and end dates and times suitable for the session, add 30 mins to 1hr extra onto the scheduled end time.
  • Early entry: 15 minutes before start time.
• Click create, this will create the session link, make a note of this for the emails.

Checklist

Complete as necessary (dependent on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• attendance reminder email
• set up blackboard session
• setup email
• joining email
• feedback email

Once all tasks are complete, please close issue.

Prepare materials for session on 26/7/22 for David

All instructors (lead and support) need to do some preparation (especially to repos in their own accounts) if they have created materials during a previously run course. Lead instructor has some extra prep steps.

Complete as necessary (dependant on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• Delete git-lesson repo from instructor's GitHub account. Delete local copy if you want to use same location for demo.
• Delete collaborative_github_exercise fork repo FROM INSTRUCTOR'S ACCOUNT ONLY. Do NOT delete the RSE-Sheffield original repo. Delete local copy (of fork!) if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear previously submitted parameter files from params/ folder in RSE-Sheffield/collaborative_github_exercise repo. DO NOT DELETE params_tmpl.R. Synch local and remote repos.
• Delete python-calculator repo from instructor's account. Delete local copy if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear collaborative team formation googledoc

Once all tasks are complete, please close issue.

Schedule emails for session on 3rd October for Bob

Emails need to be scheduled via eventbrite ahead of each session.

Emails

There are up to 4 emails that need to be scheduled for this course. There are parameterised .Rmd templates in the emails/ directory to generate the contents of these emails.

• 2 weeks prior to the event - attendance_reminder_email.Rmd: an attendance reminder to encourage participants who cannot attend anymore to cancel

• 1 week prior to the event - setup_email.Rmd: a reminder of the setup instructors as well as information about the session platform and joining link

• On the morning of the event - joining_reminder_email.Rmd: A reminder of the joining link

• Day after the event - feedback_survey_email.Rmd a request to complete a survey.
  The parameters required are:

• lead_instructor: name of the lead instructor

• session_joining_link: link to the blackboard collaborate room (if teaching on-line)

• event_date: the date of the session in ISO format (YYYY-MM-DD)

• event_start_time: defaults to "10:00"

• lunch_time: defaults to "13:00"

• prefilled_survey_link: the unchanging part of the survey link containing the identifier of the date of course question to be pre-populated with the event_date parameter.

To use these, open each .Rmd, edit parameters in the YAML header and knit to render to html. The html content should then be copied (from the viewer or the generated HTML document) and pasted into the eventbrite message content box.

Make sure to send a test message to yourself and to check each link prior to finalising the email.

Blackboard Collaborate Session

• Go to Blackboard Collaborate, logging in via MUSE,
• Under Organisations open COM - Research Software Engineering,
• Select Create Session and fill in the details as follows:
  • Session Name: git & GitHub through GitKraken - from Zero to Hero!
  • Guest Access: ✔️
  • Make sure that Guest role is set to participant
  • Set the start and end dates and times suitable for the session, add 30 mins to 1hr extra onto the scheduled end time.
  • Early entry: 15 minutes before start time.
• Click create, this will create the session link, make a note of this for the emails.

Checklist

Complete as necessary (dependent on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• attendance reminder email
• set up blackboard session
• setup email
• joining email
• feedback email

Once all tasks are complete, please close issue.

Prepare materials for session on 2022-10-03 to 2022-10-04 for David Wilby

All instructors (lead and support) need to do some preparation (especially to repos in their own accounts) if they have created materials during a previously run course. Lead instructor has some extra prep steps.

Complete as necessary (dependant on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• Delete git-lesson repo from instructor's GitHub account. Delete local copy if you want to use same location for demo.
• Delete collaborative_github_exercise fork repo FROM INSTRUCTOR'S ACCOUNT ONLY. Do NOT delete the RSE-Sheffield original repo. Delete local copy (of fork!) if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear previously submitted parameter files from params/ folder in RSE-Sheffield/collaborative_github_exercise repo. DO NOT DELETE params_tmpl.R. Synch local and remote repos.
• Delete python-calculator repo from instructor's account. Delete local copy if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear collaborative team formation googledoc

Once all tasks are complete, please close issue.

Prepare materials for session on 2022-10-31 to 2022-11-01 for Neil & Bob

All instructors (lead and support) need to do some preparation (especially to repos in their own accounts) if they have created materials during a previously run course. Lead instructor has some extra prep steps.

Complete as necessary (dependant on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• Delete git-lesson repo from instructor's GitHub account. Delete local copy if you want to use same location for demo.
• Delete collaborative_github_exercise fork repo FROM INSTRUCTOR'S ACCOUNT ONLY. Do NOT delete the RSE-Sheffield original repo. Delete local copy (of fork!) if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear previously submitted parameter files from params/ folder in RSE-Sheffield/collaborative_github_exercise repo. DO NOT DELETE params_tmpl.R. Synch local and remote repos.
• Delete python-calculator repo from instructor's account. Delete local copy if you want to use same location for demo.
• [LEAD INSTRUCTOR] Clear collaborative team formation googledoc

Once all tasks are complete, please close issue.

Add more info in setup instructions re: github/gitkraken pro

Schedule emails for session on 2022-10-31 for Neil & Bob

Emails need to be scheduled via Eventbrite ahead of each session.

Emails

There are up to 5 emails that need to be scheduled for this course. There are parameterised .Rmd templates in the
emails/ directory which should be used to generate the contents of these emails in HTML for copy and pasting into
Eventbrite.

Schedule	File	Description
2 week reminder	attendance_reminder_email.Rmd	An attendance reminder to encourage participants who cannot attend anymore to cancel.
1 Week Reminder	setup_email.Rmd	A reminder of the setup instructions as well as information about the session platform and joining link (see below for ).
4 Day Reminder	setup_email.Rmd	A reminder of the setup instructions as well as information about the session platform and joining link (see below for ).
On the Morning	joining_reminder_email.Rmd	A reminder of the joining link.
Day After	feedback_survey_email.Rmd	A request to complete a survey.

Not all templates require all parameters but across all four email templates the parameters required are:

• lead_instructor: name of the lead instructor
• session_joining_link: link to the blackboard collaborate room (if teaching on-line)
• event_date: the date of the session in ISO format (YYYY-MM-DD)
• event_start_time: defaults to "10:00"
• lunch_time: defaults to "13:00"
• prefilled_survey_link: the unchanging part of the survey link containing the identifier of the date of course question to be pre-populated with the event_date parameter.

Knitting & Sending

To use these, open each .Rmd, edit parameters in the YAML header under params and knit to render to html. If you do this in
RStudio then you can select the "Knit on Save" option. Alternatively you can knit the document
with the following, assuming your currently located in the root of the repository directory and wish to knit the attendance_reminder_email.Rmd.

rmarkdown::render("emails/<email-to-be-knitted>.Rmd")

You can run this at the command line without starting an R session using the -e flag.

R -e "rmarkdown::render('emails/<email-to-be-knitted>.Rmd')"

The html content should then be copied (from the viewer or the generated HTML document) and pasted into the Eventbrite
message content box.

Make sure to send a test message to yourself and to check each link prior to finalising the email.

Blackboard Collaborate Session

• Go to Blackboard Collaborate, logging in via MUSE,
• Under Organisations open COM - Research Software Engineering,
• Select Create Session and fill in the details as follows:
  • Session Name: git & GitHub through GitKraken - from Zero to Hero!
  • Guest Access: ✔️
  • Make sure that Guest role is set to participant
  • Set the start and end dates and times suitable for the session, add 30 mins to 1hr extra onto the scheduled end time.
  • Early entry: 15 minutes before start time.
• Click create, this will create the session link, make a note of this for the emails.

Checklist

Complete as necessary (dependent on what has been created in the past).

Tick off tasks as they are completed or if they are not required.

• attendance reminder email (2 weeks prior)
• set up blackboard session
• setup email (1 week prior)
• setup email (3 days prior)
• joining email
• feedback email

Once all tasks are complete, please close issue.