Week 1: Topics (Teaching notes)

Time (start) Duration Topic Additional materials
00:00 10 min Intro and instructor background  
00:10 15 min What you will learn  
00:25 5 min The project: CoLRev  
00:30 10 min Agenda, groups, criteria  
00:40 10 min How to make the project a success  
00:50 30 min Orientation in Open Source projects Group task, discussing solutions afterwards
01:20 10 min Next steps  
01:30 90 min Overall  

In this session, our goal is to familiarize ourselves with open-source projects on GitHub.

Intro and instructor

Introduce myself/instructor

  • I code a lot - you see in the activity chart when I took vacation
  • It takes 10 years to become good at something
  • Git/Python/R: for my research projects
  • Enjoyment/challenge/making an impact: that’s what I want you to experience in this project.

Introduce the teaching assistant

Learn about students

  • Degree program (WI/ISM?)
  • Experience in programming, in git/python, open-source development? - always helpful
  • We “only” need InfEinf or EiAPS and JaP (after the Winter Term of 2024/2025). If you have not completed these, participate in the project in the next semester(s)

What you will learn

Git/GitHub

Highlight the rapid diffusion of Git/GitHub (Microsoft paid 7.5 billion = Milliarden) and the massive investments to change versioning systems (core infrastructure)

Ask students why Google, AirBnB etc. would publish code?

  • Open Source works better
  • Identify and attract talent (they may be very picky)

Python

  • Highlight: not throw-away code!

Open-Sourcing

  • Github platform: tests, continuous integration, forks, …
  • Roles: developer and maintainer
  • Published code contribution as an opportunity to develop a profile
  • Highlight: your contribution will be public/used by others!

The project: CoLRev

  • Ambition: Open-source environment for literature reviews (like R for statistics, or Python for ML)
  • Ask students: who has already completed a literature review?
  • Mention that our approach currently focuses on the command line. What are the possible reasons?
  • Git as an inspiration: rapid adoption (not because there were shiny interfaces, but because the data management was very efficient, reliable, and scalable to large teams)

Agenda

  • Outline the sessions
  • Highlight that we offer in-person hacking sessions in the main work phase (week 6-11)
  • Very easy to schedule (Calendly), on short notice, online or in-person, the whole team or part of it
  • We will discuss the current progress and next steps
  • We will help you solve the challenging tasks (we will not solve them for you)
  • Be prepared for the meeting: be able to explain the problem, describe and evaluate the different options you know
  • The hacking sessions should ensure a steady development flow. If you get stuck for more than a couple of days, meet with us! In the hacking sessions, we will not tell you the solution directly, but we will work on it together. After the session, you will have solved the issue and/or know how to continue. (TODO: require issues)

If you are stuck for more than 2 days, schedule a meeting with us.

Show the Calendly tool (how to book a session)

How groups will form

  • We do not assign you to groups. You assign yourself by starting to contribute (issue discussions and code).
  • You have to signal your intent to contribute by contributing to the issue discussions.
  • Choose issues strategically - only the first 5 contributors will be accepted for the group.

The process resembles open-source projects, involving self-selection (instead of fixed assignment to groups), communicating in public issues, creating pull requests You can select the topics that you are interested in by contributing code.

Organize …

Sign-up

  • You can only contribute to a group if you have signaled your intent in the issue discussion before.
  • Your participation will be confirmed and your account will be linked to the project issue.

Prior experience:

  • The process has worked very well in previous semesters.
  • Please let us know if there are any problems in finding a group.
  • We reserve the right to change groups (use fixed assignments) if needed.

We have several incentives to start contributing early instead of creating a large commit at the end.

Criteria

Clear message:

  • You have to learn Git and Python. I will provide an introductory session, but you will need to invest more time.
  • You are expected to set up your environment. We are available to answer questions, but we cannot setup individual machines.
  • Everyone is expected to program and contribute. With git, we see contributions, which prevents free-riding.

How you can make the project a success

See slides

How the project may benefit you

  • Highlight: your contribution will be public/used by others!

Finding things in an Open Source project

Small groups web research task (“scavanger hunt”)

  • Assessing open-source projects and finding things are important skills.

After 12-15 mins: ask whether students have completed the task (give more time if necessary).

Solutions

  • Readme
  • Readme: Related work
  • Documentation link
  • License and CONTRIBUTING.md
  • Issue template
  • Issues / Pull-requests tabs (e.g., good-first-issue label as a typical starting point when joining an open-source project)
  • Actions with log
  • Unpaywall: search in the docs
  • Issues -> Milestones

These are issues that users of CoLRev may ask themselves (or we when we select libraries)

Discuss software selection criteria (for open-source projects) more broadly. What would you look for? Nr commits/issues,… Why?

Discuss/explain the git/open-source community structure

Until next session

Study colrev docs

Explore issues in the milestone.

Show that each issue has specific pointers to the code

Register:

  • Student e-mail address: wegen Codespaces Kontingent

Challenge: set up your own environment

Any questions?

Briefly show/explain the page: materials and deliverables

Mention our comprehensive improvement efforts. We already have very good evaluations, but we stretch to improve even more!

  • Encourage feedback (last slide)
  • Show issues (improvement): https://github.com/digital-work-lab/open-source-project/issues/8
  • We invest a lot of effort (show https://github.com/digital-work-lab/open-source-project/graphs/contributors)
  • We even published a Teaching Tip (on Git)