This is an activity development page for Open Science Comes to Campus

Topic: Contributing to open source scientific software

Notes about activity

Goals

Attendees should have the concrete experience of contributing to open source scientific software so that they can imagine themselves doing so in the future. They should confront some of the barriers to contribution in a setting where they can be helped to view these barriers as part of the learning process and not anything they're doing wrong.

Specific goals:

Participate in a successful contribution as part of a group.
Make a "toy" contribution themselves & practice basic version control skills.
Begin the process of selecting an issue for them to personally work on, and talking through together how they'd solve it.

Related work

This will incorporate elements of OSCTC's practicing git activity.

Overall structure

I'm not certain about how to structure it. Should the git toy project be a dependency outside of this lesson? Other modules, such as the 'create your own open research project', could also use an intro to git. For now, let's have it as one activity with three distinct sections.

This module can run with one instructor but likely benefits from having at least one helper for every 4-5 students. This is especially true of the 2nd and 3rd steps.

This module would really benefit from using a projector, especially for the 1st step, if there are more than 4-5 students participating.

There should definitely be breaks between each section.

Brainstorming

This is the place for ideas about what to include in the presentation/activity. I find it useful to use the goals above as prompts for brainstorming.

The Activity Itself

Part One: Group Contribution

Estimated time: 30-40 minutes

Prep work: Before the event, choose an open science project that the person leading the group contribution is comfortable with (can be something they maintain, but doesn't have to be). They should pick a task to work on as a group. A good task will be limited in scope, such that it can be completed in 30-40 minutes or less; it will not require having to understand complex elements of the project; the development environment setup should not be simple, without many complicated dependencies. Ideally, the activity leader will actually make the fix on their own, then discard their work, to ensure that there are not hidden roadblocks.

Notes: The demo activity described below can be done in a few ways. The activity leader could simply walk through the steps below. That said, the leader is already very familiar with the project, so is not the best example for students to see. Ideally, a mentor who is not familiar with the project will actually undertake the steps with guidance from the activity leader. Alternatively, if there is a willing student, they could walk through the process. Regardless of who is actually controlling the keyboard, students should be constantly asked for input about what to do next. Shauna, Bill, and other OSciCTC leads can help decide what option is best, and help you prepare this activity in general.

Activity:

Step 1: Understand the issue
- To understand the issue, go through these questions:
  - What behavior is the software exhibiting? What behavior does the issue reporter expect or wish to see?
  - What technologies does the project use? Which will we have to interact with? Are we comfortable with them or do we want to find some documentation?
  - Will we need to set up the development environment? Do we have instructions for how to do so?
Step 2: Set up the development environment
- Find the setup instructions for the project and follow them. (Note: this will sometimes surface inaccuracies and ommissions in the instructions. In that case, walk through the steps of reporting this as an issue in the issue tracker, and then switch to the activity leader's computer, which presumably has the development environment set up.)
Step 3: Making & Testing changes
- The exact steps here will depend on the issue & project at hand. Key skills to focus on are:
  - Finding where to make changes in the repository. Can we search the repository for a key phrase?
  - How does testing work? How do we run this projects'? What do we do if our changes break the tests?
Step 5: Submit changes
- Go through the process of submitting your changes. Make sure to distinguish between general steps (how to make commits in git) and project-specific steps (for instance, if the project requires certain syntax in commit messages or names for branches).

Part Two: Github Practice Activity

Estimated time: 30-60 minutes

Prep work: The toy repositories need to be set up ahead of time, and access granted to the mentors leading the activity. See here for details.

Notes: This activity can be led by a single person, but is better done in small groups with 1 mentor for every 4-5 students.

Activity: Student instructions Instructor prep

Part Three: Find a Project/Task

Estimated time: 15-120 minutes (aka very variable)

Prep work: None

Notes: This part of the module is self-guided, as students take on issues of their own. The role of mentors is to help where students get stuck. That said, the activity should start off with everyone in sync through the first two steps. It should be emphasized to the students that they are not expected to finish this process today!

Activity:

Step 1: Pick a Project
- Students should be strongly encouraged to pick Mozilla Science Lab, the demo project from the first activity, or the project they researched during the open science communication activity. If they chose the third option - or a new project that they're excited about - they should check that there are good instructions for getting started, and that the installation guide has instructions for their operating system.
Step 2: Pick a Task
- Students should browse through issue trackers and understand issues by asking the questions above, ("What behavior is the software exhibiting?", etc) When they don't know the answers, they should be encouraged to ask through communications channels. If they can't figure out the answers, alone or with help, they should look for a new task.
- Note: This is where students will start going at different paces.
Step 3: Set Up the Development Environment
Step 4: Make & Test changes
Step 5: Submit changes