Open Source Participation: Two-Week Online Course

A two-week online course on participating in open source, using Smarter, which is developed in public with issues, discussions, pull requests, code review, conventional commits and automated releases. Smarter is licensed under the AGPL-3.0, has twenty-two contributors and more than five hundred automated releases, checks every commit message with commitlint, versions itself with semantic-release on main, next, beta and alpha, and publishes its rules in CONTRIBUTING.md, CODE_OF_CONDUCT.md and SECURITY.md. A merged pull request is a public, verifiable piece of work for a student’s portfolio. There are six 30-minute recorded lectures and a 90-minute live session each week. Week 1 covers how projects work and the first contribution, and week 2 covers code contributions, review and community. See Course Formats and Grading for the format, the grading scale and the course policies, and Open Source Participation for an overview of the subject.

At a Glance

Students

Anyone who can use Git, often as a capstone to another course.

Deployment

A GitHub account and a fork for each student. Students making code contributions run Smarter from source.

Workload

3 hours of instruction and 4 to 6 hours of assignments each week.

Cost

Free.

Note

Contact the maintainers in GitHub Discussions at least two weeks before the course. Grade the contribution and the process, not whether it was merged, because volunteer reviews follow the project’s schedule.

Learning Objectives

By the end of the course, students can:

  1. Explain how open source projects are organized and governed.

  2. Explain what the major licenses allow and require.

  3. Find suitable issues and agree an approach with maintainers.

  4. Make documentation and code contributions that follow a project’s conventions.

  5. Give and respond to code review professionally.

Technical Prerequisites

  • Required: Git, including rebasing and resolving merge conflicts.

  • Required: a GitHub account, and forks, issues and pull requests.

  • Required: the command line and a text editor.

  • Required: Markdown and reStructuredText; Python or JavaScript for code contributions.

  • Helpful: Docker.

Schedule

The files that the lectures refer to are listed in full under Smarter in the Source Code.

Week

Item

Content

1

Lecture 1 (30 min)

How open source works. Motivations, roles, governance and economics; a tour of Smarter on GitHub.

1

Lecture 2 (30 min)

Licenses. Permissive and copyleft licenses, the AGPL, and compatibility.

1

Lecture 3 (30 min)

The first contribution. Reading the rules (Contributing), finding documentation problems, and the pull request workflow.

1

Live session 1 (90 min)

Live walkthrough of a documentation pull request, from fork to review. Students start their own. Start Assignment 1.

2

Lecture 4 (30 min)

Code contributions. Choosing an issue, asking first, conventional commits, tests, hooks and CI.

2

Lecture 5 (30 min)

Code review. Reviewing and being reviewed, and the pace of volunteer projects.

2

Lecture 6 (30 min)

Community. Security reports, triage, discussions, the code of conduct, and becoming a maintainer.

2

Live session 2 (90 min)

Capstone presentations (about 5 minutes each, with 2 minutes of questions).

Assignment 1 is due at the end of week 1, Assignment 2 in the middle of week 2, and Assignment 3 and the capstone at the start of Live session 2.

Smarter in the Source Code

Every lecture, lab and assignment in this course works with the files and pages below, on the main branch of github.com/smarter-sh/smarter, so that students can open each one during class.

The Rules of the Project

Topic

What Smarter has

Where to look

The license

The GNU Affero General Public License, version 3: copyleft that also applies when a modified version is offered to users over a network.

LICENSE

Contributing and conduct

How to contribute, and the code of conduct that every participant agrees to. Contributing, Code of Conduct.

CONTRIBUTING.md, CODE_OF_CONDUCT.md

Reporting a vulnerability

A private email address for security reports, and a request not to open a public issue.

SECURITY.md

Issues and pull requests

Forms for bug reports and feature requests, and a pull request template that asks for the type of change and the issue it resolves.

.github/ISSUE_TEMPLATE/, PULL_REQUEST_TEMPLATE.md

Who reviews

A CODEOWNERS file that names the reviewers for each path, and a single maintainer today: a real case for a discussion of the bus factor.

.github/CODEOWNERS

Funding

How the project can be sponsored.

.github/FUNDING.yml

From Commit to Release

Topic

What Smarter does

Where to look

Conventional commits

Every commit message is checked by commitlint, with the conventional and Angular rules, because the release tooling reads them.

commitlint.config.js, smarter-git-commits/SKILL.md

Pre-commit hooks

Formatting, linting, spelling, security scans and secret detection on every commit.

.pre-commit-config.yaml

Automated releases

semantic-release turns commits into versions on four branches: main and next, and prereleases on beta and alpha. There have been more than five hundred releases. Semantic Versioning Guide.

release.config.js, releases

Changelogs

Generated from the commits, one file for the current release and one for each older minor version.

CHANGELOG.md, changelogs/

Dependency updates

Dependabot proposes updates as pull requests, and a weekly workflow bumps the pre-commit hooks.

.github/dependabot.yml, precommitVersionBumps.yml

Where to Contribute

Place

What students can do there

Where to look

Issues

Find work, labeled good first issue, help wanted, documentation, bug or enhancement, and ask about an approach before writing code.

issues, labels

Discussions

Questions, ideas, and arranging a class’s contributions with the maintainers.

discussions

Pull requests

See how changes are proposed, reviewed and merged, including commits whose bodies explain every change.

pull requests

The documentation

More than nine hundred pages in reStructuredText, the easiest first contribution. Documentation Style Guide & Technical Reference.

docs/source/

The other repositories

The CLI in Go, the chat component in TypeScript, the VS Code extension, the Python SDK and the Terraform, each smaller and easier to start with than the platform.

github.com/smarter-sh

Graded Assignments

Assignment 1: Rules and Licenses

Students answer ten questions about how to contribute to Smarter, with citations, and compare four licenses on five scenarios.

Turn in: the answers and the license table.

Criterion

Pts

Exemplary

Developing

Contribution rules

8

All correct and cited.

Several wrong.

License analysis

8

All scenarios correct, with reasons.

Several wrong.

AGPL network clause

4

Explained correctly.

Vague.

Assignment 2: A Documentation Pull Request

Students open a documentation pull request that fixes a genuine problem.

Turn in: a link to the pull request.

Criterion

Pts

Exemplary

Developing

Real improvement

7

Genuine problem fixed.

Trivial.

Conventions

6

Conventional commit; hooks pass.

Fails.

Description

5

Clear.

Empty.

Scope

2

Focused.

Mixed.

Assignment 3: Peer Review

Students review two classmates’ pull requests in GitHub, then respond to the reviews of their own.

Turn in: links to the reviews given and the responses.

Criterion

Pts

Exemplary

Developing

Review quality

8

Specific, actionable and kind.

“Looks good” or harsh.

Coverage

4

Correctness, clarity and conventions.

One aspect.

Responses

6

Thoughtful, with changes made.

Ignored.

Tone

2

Professional.

Unprofessional.

Capstone Projects

Students choose one, and present it in Live session 2.

Capstone A: A Code Contribution

Learning objective. See a real code contribution through an open source project’s process.

Students choose a good first issue (or one agreed with the maintainers), discuss the approach in the issue, implement it with tests, and open a pull request upstream.

What students turn in:

  • Links to the issue discussion and pull request.

  • A process log and a short reflection.

  • A five-minute presentation.

How it is graded (100 points):

Criterion

Pts

Exemplary

Developing

Process

25

Agreed before coding.

No discussion.

Code quality

25

Patterns, tests and hooks.

Failing checks.

Pull request

15

Clear and focused.

Unclear.

Review response

20

Professional, with changes.

Ignored.

Reflection and presentation

15

Thoughtful.

Generic.

Capstone B: A Documentation Contribution

Learning objective. Make a substantial documentation contribution that helps real users.

Students agree a documentation need with the maintainers, write it, test it on a reader, and open a pull request upstream.

What students turn in:

  • Links to the discussion and pull request.

  • Reader test notes and a process log.

  • A five-minute presentation.

How it is graded (100 points):

Criterion

Pts

Exemplary

Developing

Process

20

Scope agreed.

Unannounced.

Value

25

Real gap; reader tested.

Marginal.

Accuracy and markup

20

Verified and valid.

Errors.

Review response

20

Professional.

Ignored.

Reflection and presentation

15

Thoughtful.

Generic.

Further Study