# Collaboration Workshop with GitHub

## About
The "Collaboration Workshop with GitHub" is a generalized workshop that has been built upon Malvika Sharan's [Developing Collaborative Documents](https://github.com/malvikasharan/developing_collaborative_document), [Mozilla Science Lab's Study Group Orientation](https://mozillascience.github.io/study-group-orientation/), and Kirstie Whitaker's [Friendly GitHub Intro](https://github.com/KirstieJane/friendly-github-intro). </br>

It is intended to give participants an introduction to using GitHub to collaborate with colleagues, and the basic skill set to collaborate on an existing project. </br>

Although each workshop will be slightly different, we have identified a few core learning objectives that successfully land with the intended audience. If you are creating an iteration of the workshop, please ensure that you either address or adjust these objectives to your specific session's needs.

## Learning Outcomes
* Familiarize participants with the common language of GitHub (Commit, Main, Branch, Fork, Pull Request) and what functionality they relate to.
* Understand the workflows that support collaborative work on GitHub
* Practice the following skills:
* adding resources to an online project folders
* working with tasks and issues
* writing messages when committing any changes
* making a pull request
* merging a pull request

## Running the Workshop

### Before the session
* Define the goal for this project.
* Decide on the date, time, and venue for the course.
* Define your target audience and their requirements.
* Ensure that the repositories you will be using have appropriate documentation which includes
* a README file that follows best practices
* a License
* Contributing Guidelines and/or a Code of Conduct
* Create a check in document on your platform of choice (HackMD, Etherpad, Google Docs, or using a GitHub Issue)
* Create the issues on the repository that you will have people editing. Examples of this can be found [here](https://github.com/alan-turing-institute/the-turing-way/issues/2486), [here](https://github.com/aim-rsf/Glossary-of-Terms/issues/21), and [here](https://github.com/alan-turing-institute/the-turing-way/issues/2697) if you are using Issues as tasks.

### During the session

* Attendees are to write their names, or other content and GitHub usernames in either a numbered list (if you are using an external file when running this course online) or by commenting on an Issue (suggested if running in person), the co-facilitator will then add the corresponding numbers to the Introductions.md file, or reply to the comments on the issue with a number.
* When it's time to do the introductions exercise, please ask participants to write their names on the line with the corresponding number in order to avoid merge conflicts.
* If your workshop intends to discuss merge conflicts, we suggest creating one ahead of time and demonstrate solving it.
* Ensure that one of the 2 exercises allows your participants to Merge their own PRs
* in order to do this, the co-facilitator will need to directly invite participants as collaborators on a repository.

### Suggestions
* For the AIM RSF Glossary of Terms workshop:
* it will be really really important to not let people merge the PRs of the glossary of terms repo themselves in the workshop as we’ll need to do a full proper code review as there’s the CI/CD that’s been set up and I haven’t had a chance to put checks or tests on things yet.
* Basically if someone pushes something to main or the gh-pages branch it may bring down production. Nothing that isn’t fixable but it’s easier if it can be avoided.
* It’s nice if the co facilitator approved one safe and checked PR and then does the demo of approving it. We’ve done it once we’ve the demo issue and PR was then reviewed live too (i.e. Anne made the PR and then I took over screen sharing to review her PR and approve it then she took screenshare back and merged it).

### Other Tips
* It can be helpful if you have a second GitHub account to do that part of the demonstration on so that people twig onto having to accept the invitation to be a collaborator on a repoistory before they can edit.
* in the breakout rooms having facilitators roam around to help.