Case study: running an open source project

The last session, on April 8, 2027, was about the project that had been in the background all spring: open-trail-report, a simple, open format for describing trail conditions, such as closures, washouts, ice and water levels, that any website or app could read. Malik Osei had started it two years earlier in his personal account, as a hobby. TrailCheck used it, two university hydrology groups used its data, and a parks volunteer network in northern New England wanted to. It had 140 stars, 11 contributors and one exhausted maintainer. Malik and Tidewater had agreed that the project would move into the tidewater-guides organization, stay open source, and be run properly. This lesson follows the plan the team made that day, which uses almost every topic in the course.

Step 1: move the repository into the organization

A repository can be transferred from a personal account to an organization by its owner, if the person has permission to create repositories in the organization. A transfer keeps the repository's history, issues, pull requests, wiki, stars and watchers, and GitHub redirects the old address to the new one, so existing links and clones keep working, although contributors should update their remotes. Malik transferred malik-osei/open-trail-report to tidewater-guides/open-trail-report. Because his personal repository had only owner and collaborator access, lesson 2's roles now became available, and lesson 1's teams could replace individual grants.

Step 2: settle the license

The project had an MIT license for the code, a short license that permits reuse, including in commercial products, as long as the copyright notice is kept. The trail reports themselves were a different matter: data is not code, and the volunteer network wanted to know whether it could republish reports. The team added a second license, a Creative Commons Attribution license, for the data folder, and explained in the README which license covers which files. Because the project had outside contributors, they also added a short statement to CONTRIBUTING.md that contributions are accepted under the project's licenses, so the rights to new contributions are clear. A license is the one community file that cannot come from organization defaults (lesson 5), so it lives in the repository itself.

Step 3: governance and community files

Next came the files that tell strangers how the project works. The organization's .github repository already supplied the code of conduct, contributing guide and support file (lesson 5). The project added its own GOVERNANCE.md, with the roles from lesson 5: contributor, reviewer, maintainer and lead. It added a SECURITY.md specific to the validator, and turned on private vulnerability reporting (lesson 7). It also added a CITATION.cff file for the researchers, issue forms for new report types and bug reports, and a pull request template asking for a sample data file with every format change.

Step 4: protection and automation

With outside contributors, review is the main safeguard. Priya applied the protect-main ruleset from lesson 3: pull requests with one approval from a code owner, dismissal of stale approvals, resolved conversations, a passing validate-data check, no force pushes or deletions, and signed commits. A tag ruleset protects release tags. Workflows from forks run without access to secrets, so contributors' pull requests are checked safely. The only outside actions in the workflow are pinned to commit identifiers (lesson 6), and Dependabot keeps them and the validator's dependencies current, with a weekly grouped update (lesson 8).

# .github/CODEOWNERS
* @tidewater-guides/maintainers-trail-report
/schema/ @malik-osei @priya-nair
/data/ @tidewater-guides/maintainers-trail-report @owen-tremblay

Step 5: security from day one

Because open-trail-report is public, the main security features cost nothing: the dependency graph, Dependabot alerts and security updates, secret scanning with partner alerts, push protection, and CodeQL code scanning on the validator with the default setup. Priya turned all of them on with the organization's security configuration, set herself and Malik as the people to notify, and added the repository to the Monday alert review from lesson 7. The volunteer's leaked key in lesson 9 had come from this repository, so the contributing guide gained a line asking people to remove credentials from logs before pasting them.

Step 6: making it welcoming

Malik's experience was that most first-time contributors give up not because the work is hard but because nobody answers. The team agreed on four habits. Label small, well-described tasks good first issue and keep at least three open, because GitHub surfaces repositories with such issues to people looking for a first contribution. Reply to every new issue and pull request within three working days, even if only to say when a full review will happen. Thank contributors by name in the release notes. And keep the conversation about the format in Discussions, with an Ideas category for proposed new fields and a Q&A category for how-to questions, so issues stay a list of work.

Step 7: releases and versioning

Data formats need stability, because other people's software reads them. The project adopted semantic versioning from MSBA-160: a new optional field is a minor release, such as 1.3.0; a correction to the documentation or validator that changes no data is a patch, such as 1.3.1; and anything that would make existing files invalid is a major release, such as 2.0.0, announced in Discussions at least two months ahead. Releases are created on GitHub from protected tags, with release notes generated from merged pull requests and edited by hand, and a sample data file attached to each release.

Step 8: funding with GitHub Sponsors

GitHub Sponsors lets individuals and organizations make one-time or monthly payments to developers and organizations whose open-source work they depend on. A sponsored account has a profile that explains what the money supports, with sponsorship tiers at different amounts, optional rewards such as a name in the README, and optional public goals. Sponsorships appear on the sponsor's and the sponsored person's profiles unless the sponsor chooses to be private. The FUNDING.yml file adds a Sponsor button to the repository that links to the profile and to any other funding pages. Malik set up a Sponsors profile; Tidewater became his first organization sponsor; and the two university groups asked their departments about doing the same.

Step 9: moderation and community health

Public projects attract the occasional hostile comment and, around a popular release, bursts of spam. Malik is the project's moderator (lesson 1), so he can hide comments, lock heated threads, block people who break the code of conduct, and set temporary interaction limits if a flood arrives. The team agreed that every moderation action gets a short, polite explanation, as lesson 5 recommended, and that conduct reports go to the shared mailbox so Malik is never the only person handling a report about someone he works with. The community profile under Insights now shows every recommended item complete.

Step 10: planning for succession

The reason Malik was exhausted was that the project had a bus factor of one: if he stopped, nobody else knew how to cut a release, answer a security report or decide on a format change. Moving the repository into an organization fixed ownership; it did not by itself fix knowledge. So the team wrote down every recurring maintainer task in a MAINTAINING.md file, each with the steps and the access it needs, and paired a second person with Malik on each task at least once before July. Owen took the data reviews and the release notes, Priya took security and the validator, and Malik kept the schema and the final say on format changes, as the governance file says.

The same document says how a reviewer becomes a maintainer: after a sustained record of good reviews, an existing maintainer proposes them in a discussion, and the maintainers agree by consensus. Making the path visible matters as much as the rota. Contributors who can see how responsibility is earned are more likely to stay, and a project that adds a maintainer every year or two never ends up depending on one tired person again.

Step 11: knowing whether it is healthy

Finally, the team chose a few numbers to watch each quarter, all visible in the repository's Insights tab or easy to count: the time to first response on new issues and pull requests, the number of contributors who made their first contribution, the number of open good first issues, the share of pull requests merged versus closed without merging, open security alerts, and the number of dependents, other public repositories that use the format. Stars were noted but not targeted, because they measure interest rather than health.

Looking back over the course

Owen closed the session by mapping each step back to the course. Organizations, teams and roles (lessons 1 and 2) gave the project an owner that would outlast any one person. Rulesets (lesson 3) made outside contributions safe to accept. Markdown and community health files (lessons 4 and 5) told strangers how to take part. Marketplace tools (lesson 6) were chosen by their permissions, not their popularity. The security features (lessons 7 to 9) watched dependencies and secrets for free. The plan (lesson 10) cost nothing extra because the work was public. And inner source (lesson 11) was the habit that made it natural for staff to contribute. The exam readiness course, MSBA-169, reviews all of it against the GH-900 skills outline before Owen's exam at the end of April.