Open Source Participation: Classroom Bootcamp

An eight-hour classroom bootcamp 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. Students learn how a project works, make a first documentation contribution during the day, and leave with a code or documentation contribution under way. See Course Formats and Grading for the standard bootcamp day, 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: developers, technical writers, designers and students, often as a capstone to another course.

Deployment

Each student has a GitHub account and a fork of the repository. Students making code contributions run Smarter from source.

Cost

Free.

Note

Contact the maintainers in GitHub Discussions at least two weeks before the bootcamp, so that they can label suitable issues and plan for the reviews. Students’ pull requests are reviewed by volunteers, on the project’s schedule, not the course’s, so grade the quality of the contribution and the process, not whether it was merged.

Learning Objectives

By the end of the bootcamp, students can:

  1. Explain how an open source project is organized: maintainers, contributors, governance, and the documents that set the rules.

  2. Explain what the major licenses (AGPL, GPL, Apache and MIT) allow and require.

  3. Choose a suitable issue, and discuss an approach with maintainers before writing code.

  4. Make a contribution that follows a project’s conventions: branch, conventional commits, tests, documentation and a clear pull request.

  5. Respond to code review professionally.

Technical Prerequisites

  • Required: Git: clone, branch, commit, rebase, push, and resolving a simple merge conflict.

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

  • Required: the command line, and a text editor.

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

  • Helpful: Docker (for running Smarter), and familiarity with the project from another course.

Schedule

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

Block

Min

Content

1

45

Lecture 1: How open source works. Why people and companies contribute, maintainers and contributors, governance, and the economics of open source. A tour of Smarter’s issues, discussions, pull requests and releases.

2

45

Lab 1: Read the rules. Read Smarter’s contributing guide, code of conduct, developer guidelines and SECURITY.md, and answer questions about how to contribute. Produces Assignment 1.

3

45

Lecture 2: Licenses. Copyright, permissive and copyleft licenses, the AGPL and network use, contributor agreements, and license compatibility.

4

45

Lab 2: Compare licenses. Compare the AGPL-3.0, GPL-3.0, Apache-2.0 and MIT licenses on five scenarios (for example “a company runs a modified version as a web service”). Produces Assignment 2.

5

45

Lecture 3: The contribution workflow. Finding an issue, asking first, forking and branching, conventional commits, pre-commit hooks, tests, and writing a pull request. Semantic Versioning Guide.

6

45

Lecture 4: Documentation contributions. Why documentation is the easiest first contribution and one of the most valued; finding unclear pages; reStructuredText basics.

7

45

Lab 3: A first contribution. Find and fix a documentation problem (a typo, a broken command, a missing example), and open a pull request. Produces Assignment 3.

8

45

Lecture 5: Code review. What reviewers look for, how to respond to comments, how to review others’ work kindly, and how long reviews take in volunteer projects.

9

45

Lab 4: Review each other. Students review two classmates’ pull requests from Lab 3, with comments in GitHub. Ungraded.

10

45

Lecture 6: Beyond the first pull request. Security reports, triaging issues, helping in discussions, becoming a maintainer, and open source on a résumé. Project health, read from Smarter’s own CODEOWNERS: what a single maintainer means for a project, and how contributors change that.

11

30

Capstone kickoff. Students choose an issue and post their proposed approach in it.

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: How to Contribute

Students answer ten questions about how to contribute to Smarter (for example: where to ask a question, how to report a vulnerability, what a commit message must look like, what must pass before review), citing the document that answers each.

Turn in: the answers with citations.

Criterion

Pts

Exemplary

Developing

Correct answers

12

All ten correct.

Several wrong.

Citations

6

Each answer cites the right document and section.

Missing citations.

Clarity

2

Concise.

Rambling.

Assignment 2: License Comparison

Students compare four licenses on five scenarios, and explain the AGPL’s network clause.

Turn in: a table and a one-page explanation.

Criterion

Pts

Exemplary

Developing

Scenario analysis

10

All twenty cells correct, with reasons.

Several wrong.

AGPL explanation

6

Explains the network clause and why Smarter chose it.

Vague.

Clarity

4

Clear.

Confusing.

Assignment 3: A First Pull Request

Students open a documentation pull request to Smarter (or to their fork, if the maintainers prefer that for a large class).

Turn in: a link to the pull request.

Criterion

Pts

Exemplary

Developing

Real improvement

7

Fixes a genuine problem.

Trivial or unnecessary change.

Conventions

6

Conventional commit, branch, hooks pass.

Commit message or hooks fail.

Pull request description

5

Explains the problem and the change.

Empty.

Scope

2

Small and focused.

Unrelated changes mixed in.

Capstone Projects

Students choose one. Capstones are due one week after the bootcamp. Grade the contribution and the process, not whether the maintainers have merged it by the deadline.

Capstone A: A Code Contribution

Learning objective. See a real code contribution through an open source project’s process, from issue to review.

Students choose an issue labelled good first issue (or another 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 the pull request.

  • A one-page log of the process: the discussion, the decisions, the review comments and the responses.

  • A short reflection on what they learned about the project and about collaboration.

How it is graded (100 points):

Criterion

Pts

Exemplary

Developing

Process

25

Approach agreed in the issue before coding.

Pull request opened without discussion.

Code quality

25

Follows the project’s patterns; tests and hooks pass.

Inconsistent, failing checks.

Pull request

15

Clear description, small focused commits.

Unclear.

Review response

20

Responds promptly and professionally, with changes.

Ignores or argues with review.

Reflection

15

Specific and thoughtful.

Generic.

Capstone B: A Documentation Contribution

Learning objective. Make a substantial documentation contribution that helps real users, through an open source project’s process.

Students choose a documentation need (ask in GitHub Discussions), such as a missing tutorial, an outdated guide or an undocumented feature, agree the scope 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 the pull request.

  • Notes from the reader test.

  • A one-page log of the process and review.

How it is graded (100 points):

Criterion

Pts

Exemplary

Developing

Process

20

Scope agreed with maintainers.

Unannounced.

Value to users

25

Fills a real gap; tested on a reader.

Marginal; untested.

Accuracy and markup

20

Verified; valid markup; links work.

Errors.

Review response

20

Professional, with changes.

Ignored.

Reflection

15

Thoughtful.

Generic.

Further Study