Open Source Participation: Four-Week Online Course

A four-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 twelve 30-minute recorded lectures and a 90-minute live session each week. Week 1 covers how projects work and their licenses, week 2 the first contributions, week 3 a substantial contribution and review, and week 4 community, security and sustainability. The four weeks give time for a contribution to go through real review. 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, installed in week 2.

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, so that they can prepare issues and plan reviews. Grade the contribution and the process, not whether it was merged.

Learning Objectives

By the end of the course, students can:

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

  2. Explain and compare the major licenses, and how they apply to real scenarios.

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

  4. Give and respond to code review, and take part in a project’s discussions.

  5. Report security issues responsibly, and assess a project’s health.

  6. Plan a sustained contribution, and present open source work in a portfolio.

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.

  • Required by week 2 (for code contributions): Docker, and Smarter installed from source.

Schedule

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

Week

Item

Content

1

Lecture 1

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

1

Lecture 2

Governance and funding. Benevolent dictators, foundations, companies, sponsorship, and maintainer burnout.

1

Lecture 3

Licenses. Copyright, permissive and copyleft, the AGPL, compatibility and contributor agreements.

1

Live session 1

A license scenarios quiz, then a tour of Smarter’s issues and pull requests. Start Assignment 1.

2

Lecture 4

Reading the rules. Contributing, Code of Conduct, Developer Guidelines and SECURITY.md.

2

Lecture 5

The pull request workflow. Forks, branches, conventional commits, hooks, CI, and Semantic Versioning Guide.

2

Lecture 6

Documentation contributions. Finding gaps, reStructuredText, and testing on readers.

2

Live session 2

Review of Assignment 1. Students open their first documentation pull requests together. Start Assignment 2.

3

Lecture 7

Choosing a substantial issue. Reading an issue, estimating it, and asking first.

3

Lecture 8

Code contributions. Following the patterns, tests, docs, and a pull request that is easy to review.

3

Lecture 9

Code review. Reviewing and being reviewed, disagreement, and patience.

3

Live session 3

Review of Assignment 2. Students present their chosen issue and approach. Capstone proposals discussed. Start Assignment 3.

4

Lecture 10

Security in open source. Coordinated disclosure, CVEs, supply chain security and the OpenSSF Scorecard.

4

Lecture 11

Project health. CHAOSS metrics, bus factor, and choosing projects to depend on, applied to Smarter itself: its contributors, its release history and its CODEOWNERS.

4

Lecture 12

Sustaining contribution. Triage, helping in discussions, becoming a maintainer, and open source in a portfolio.

4

Live session 4

Capstone presentations (about 6 minutes each, with 2 minutes of questions), and a course retrospective.

Assignments 1 to 3 are due before the next live session. Assignment 4 is due in the middle of week 4. The capstone proposal is due before Live session 3, and the capstone at the start of Live session 4.

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: Licenses and Governance

Students compare four licenses on six scenarios, and describe the governance and funding of Smarter and of one well-known project of their choice.

Turn in: a license table and a two-page comparison.

Criterion

Pts

Exemplary

Developing

License analysis

8

All scenarios correct, with reasons.

Several wrong.

Governance comparison

8

Accurate, with sources.

Unsourced or wrong.

Insight

4

Relates governance to the project’s health.

Description only.

Assignment 2: A Documentation Pull Request

Students open a documentation pull request that fixes a genuine problem, and review one classmate’s.

Turn in: links to their pull request and their review.

Criterion

Pts

Exemplary

Developing

Real improvement

6

Genuine.

Trivial.

Conventions

5

Commit, hooks, description.

Fails.

Review given

6

Specific, actionable, kind.

“Looks good”.

Response to review

3

Changes made.

Ignored.

Assignment 3: Issue Proposal

Students choose a substantial issue, post a proposed approach in it, and respond to the maintainers’ feedback.

Turn in: a link to the issue comment, and a one-page plan with the files they expect to change and the tests they will write.

Criterion

Pts

Exemplary

Developing

Issue choice

4

Appropriate in size and agreed.

Too large or unclaimed.

Proposal

6

Clear approach, with questions where unsure.

“I’ll fix it”.

Plan

6

Specific files and tests, following the patterns.

Vague.

Communication

4

Responds to feedback.

Ignored.

Assignment 4: Project Health Assessment

Students assess the health of Smarter and of one dependency it uses, with CHAOSS metrics and the OpenSSF Scorecard, and recommend one improvement for each.

Turn in: a two-page assessment with data.

Criterion

Pts

Exemplary

Developing

Data

7

Real metrics from the repositories and Scorecard.

Impressions.

Interpretation

6

Careful about what the metrics mean.

Overclaims.

Recommendations

5

Specific and realistic.

Generic.

Clarity

2

Clear.

Unclear.

Capstone Projects

Students choose one, propose it before Live session 3, and present it in Live session 4.

Capstone A: A Substantial Code Contribution

Learning objective. See a substantial code contribution through an open source project’s process, including iterations of review.

Students implement the issue from Assignment 3, with tests and documentation, open a pull request upstream, and work through review.

What students turn in:

  • Links to the issue and the pull request, with its review history.

  • A process log: decisions, review comments and responses.

  • A two-page reflection, and a six-minute presentation.

How it is graded (100 points):

Criterion

Pts

Exemplary

Developing

Code quality

25

Follows the patterns; tests, docs, hooks and CI pass.

Inconsistent or failing.

Process

20

Agreed approach followed.

Diverged without discussion.

Review iterations

25

Responds to every comment, with changes.

Ignores review.

Pull request

10

Clear, focused, easy to review.

Sprawling.

Reflection and presentation

20

Thoughtful.

Generic.

Capstone B: A Contribution Program

Learning objective. Contribute to a project in several ways over four weeks, and build a body of public work.

Students make at least four contributions of different kinds over the course: a documentation pull request, a code or test pull request, an issue triage or a good bug report, and an answer in GitHub Discussions, and present them as a portfolio.

What students turn in:

  • Links to each contribution.

  • A portfolio page (for example, a README.md on their GitHub profile) describing the work.

  • A two-page reflection, and a six-minute presentation.

How it is graded (100 points):

Criterion

Pts

Exemplary

Developing

Breadth

20

Four kinds of contribution.

One kind.

Quality

30

Each contribution is useful and follows the project’s conventions.

Low-value contributions.

Communication

20

Professional in every interaction.

Abrupt.

Portfolio

15

Clear and honest.

Missing.

Reflection and presentation

15

Thoughtful.

Generic.

Further Study