Contributors Guide

Thank you for considering contributing to OneBusAway. This guide will help you understand what we do, why it matters, and how to get started—whether you’re an engineer, designer, writer, product manager, or transit enthusiast.

Why This Matters

OneBusAway exists to answer one question for transit riders, anywhere in the world: when is my ride coming?

That sounds small, but it’s really a profoundly important part of our transit infrastructure. Real-time transit information is a critical element of every transit system: when riders don’t know whether their bus is coming, they stop trusting the system and stop riding. Riders with reliable real-time information are more likely to use transit and report higher satisfaction with it.

Today, OneBusAway serves more than 160,000 riders in the Seattle metro area alone, and millions more worldwide through deployments at transit agencies in the United States, from San Diego to New York City, and around the world: Argentina, Australia, Bulgaria, Cyprus, Finland, Malaysia, Poland, Puerto Rico, and beyond. Every line of code, every translation, every documentation fix, and every bug report makes those riders’ lives a little easier.

But that’s the easier story. The harder, more important story is this: at least one billion people ride transit every day with no real-time information at all. Matatus in Nairobi, microbuses in Cairo, jeepneys in Manila—each of these systems move more riders daily than most US transit systems combined, with virtually zero digital infrastructure. Less than 5% of the world’s transit has machine-readable data. In other words, most riders, in most of the world, simply don’t appear on a map.

We’re building OneBusAway so that they can. Our work on next-generation server software (Maglev), flexible-route support (GTFS-Flex), and phone-based vehicle tracking is designed to make it possible for any community—a rural agency in the US, an NGO in Kenya, a university campus shuttle—to give their riders the same quality of real-time information that riders in Seattle, New York, or London expect.

When you contribute to OneBusAway, you’re working on infrastructure that ranges from a daily commute in Tampa to a billion-rider unsolved problem. Both ends of that spectrum matter, and they reinforce each other: the tools we build for under-resourced agencies abroad come home to serve US paratransit, rural dial-a-ride, and microtransit pilots that the commercial transit-tech industry has largely ignored.

About OTSF

OneBusAway is stewarded by the Open Transit Software Foundation (OTSF), a 501(c)(3) nonprofit incorporated in Washington State in 2019. OneBusAway itself is older — it was launched in 2008 by two Ph.D. students at the University of Washington — and transitioned from a university research project to a foundation-supported platform when OTSF was formed.

Most of our software is licensed under Apache 2.0. A few projects (notably Wayfinder and Waystation) are licensed under AGPL 3.0. Either way: no vendor lock-in, no licensing fees.

What Projects Exist

The full, canonical list lives at github.com/onebusaway, but here is a contributor-friendly tour.

The flagship projects

These are the projects with the most active development and the broadest impact. If you want your work to ship to the most riders, start here.

  • OneBusAway for iOS — Native Swift app with real-time arrivals, vehicle tracking, trip planning, and white-label support for agency branding. Apache 2.0.
  • OneBusAway for Android — Java/Kotlin app, similar feature set to iOS. Apache 2.0.
  • Wayfinder — Our modern JavaScript/SvelteKit web app for riders. Responsive, accessible, embeddable, localized into 24 languages with RTL support. AGPL-3.0.
  • OneBusAway Application Modules — The original, battle-tested Java REST API server that powers most production deployments today. Apache 2.0.
  • Maglev — The next-generation OBA REST API server, written from scratch in Go. Already at feature parity with the Java server, dramatically easier to set up and maintain. Apache 2.0.

Supporting projects

These tend to be smaller in scope and are excellent places to find a first issue.

  • Waystation — Digital signage / kiosk display built with SvelteKit. AGPL-3.0.
  • Watchdog — Go-based service that monitors OBA API servers and exposes Prometheus metrics. Apache 2.0.
  • OneBusAway Docker — Docker configuration and GTFS bundle build scripts for self-hosted deployments. Apache 2.0.
  • OneBusAway for Pebble — The Pebble smart watch app. Yes, it still works. Apache 2.0.

Libraries

  • onebusaway-gtfs-modules — Java library for reading and writing GTFS feeds. Apache 2.0.
  • OTPKit — Swift library for OpenTripPlanner integration on iOS. Apache 2.0.

Coming up: Vehicle Tracker

onebusaway/vehicle-positions

A free, open-source server plus an Android companion app that turns any cheap smartphone into a GPS tracker, generating standard GTFS-RT vehicle position feeds. Built for transit services that have no automatic vehicle location (AVL) hardware at all — informal transit in developing countries, rural dial-a-ride in the US, paratransit fleets, microtransit pilots, or corporate shuttles.

How to Get Started Contributing

In short: it depends on what you want to do and how much time you have. Here’s a path that works for most people.

Step 1: Join the Slack

Most coordination happens in our Slack workspace. It’s the fastest way to introduce yourself, ask questions, and get pointed toward something that fits your skills. You can join here:

opentransitsoftwarefoundation.org/join-our-slack

When you join, drop a quick “hello” in #general or #engineering-public — tell us a bit about your background and what you’re interested in working on. Someone will help you find a starting point.

Step 2: Pick a project that fits

If you already have a strong preference (you write Swift, you love Go, you want to work on accessibility), great — head to the project’s GitHub repository and dive in. Every OBA project lives under github.com/onebusaway.

If you’re not sure, here are some rules of thumb:

  • Front-end / web developers → Wayfinder or Waystation
  • Mobile developers → OneBusAway for iOS or Android, or the Vehicle Tracker project
  • Java / backend developers → Application Modules, Trip Updates, onebusaway-gtfs-modules, or the Vehicle Tracker project
  • Go developers → Maglev, Watchdog, or the Vehicle Tracker project
  • DevOps / infrastructure people → OneBusAway Docker
  • Designers, writers, PMs, translators, transit enthusiasts → see “Beyond code” below

Step 3: Find a good first issue

In each project’s GitHub repository, look for issues tagged good first issue or help wanted. These are intentionally scoped to be approachable for someone unfamiliar with the codebase.

If you can’t find one, or if the ones you find look stale, ask in Slack. We’d rather take a few minutes to point you at something real than have you spin on an outdated ticket. It’s also fine to propose your own first contribution — a bug you’ve hit, a feature you wish existed, a piece of documentation that confused you.

Step 4: Open a PR — small is better

For your first contribution, smaller is better. A typo fix in documentation, a small UI bug, a missing translation string — these are great ways to learn how the project’s review process works and to get to know the maintainers. You don’t need to start with a major feature. (and in fact we recommend against it!)

When you open a pull request, mention in Slack so it doesn’t get lost. Maintainers are mostly volunteers; a friendly nudge helps.

Step 5: Stick around

The contributors who have the biggest impact on OneBusAway are the ones who stay involved over months and years, not the ones who land one big PR and disappear. If you find a project you like, the best thing you can do is keep showing up — review other people’s PRs, answer questions in Slack, help triage issues. That’s how you become a real part of the community.

What’s My Time Commitment?

Whatever feels sustainable to you. Genuinely — there’s no minimum, no expected pace, and no implicit pressure to keep up with anyone else’s velocity. The most important thing you can do is pick a commitment you can actually hold over time.

If you’ve ever donated to a nonprofit, you’ve probably heard that recurring monthly donations are more valuable than one-time gifts of the same total amount, because they let the organization plan. Volunteer time works exactly the same way. One hour a week, every week, is far more useful to OneBusAway than a single fifty-two-hour sprint — even though the math says they’re equivalent over a year. Steady contributors become trusted reviewers, mentors for the next wave of contributors, and the people maintainers can confidently hand a feature to. One-shot heroics, however well-intentioned, often leave behind code that no one is around to maintain.

So: an hour a week is great. A focused weekend every couple of months is great. Translating one screen of Wayfinder is great. Pick whatever fits your life, and tell us in Slack what to expect — we’ll meet you there.

Beyond Code

A lot of people assume open source means “you have to be a programmer.” That isn’t true here, and we mean it. We need:

  • Product managers to help shape roadmaps across our projects
  • Designers to improve the rider experience and accessibility
  • Translators — Wayfinder is in 24 languages and counting; we’d love to add yours
  • Technical writers to improve our developer documentation and agency-facing guides
  • Mentors for Google Summer of Code contributors
  • Researchers to study transit equity, rider behavior, and the impact of real-time information
  • Outreach and community organizers to help us connect with new agencies and contributors

Our jobs board for non-engineering roles is at ossvolunteers.com.

OBACloud: How We Fund the Mission

A note on sustainability, because it matters.

OneBusAwayCloud.com is our managed hosting service for OneBusAway. We run the servers; transit agencies provide their GTFS feed; their riders get a fully managed deployment of the OBA stack — API server, web app, mobile apps, push notifications — without having to manage any infrastructure themselves. It’s currently in production with agencies like HART (Tampa) and UC San Diego.

OBACloud exists to fund our mission. Every paying customer is another engineer-week of work on Maglev, GTFS-Flex, the Vehicle Tracker, accessibility improvements, and the tools that under-resourced agencies and developing country NGOs will eventually use for free. US agencies pay for managed service; the rest of the world gets the open-source tools at no cost.

If you contribute to any OneBusAway project, you’re contributing to that flywheel. The polish you add to Wayfinder, the bug you fix in Maglev, the test coverage you add to Application Modules — all of it makes OBACloud more valuable, which generates more funding, which pays for the next piece of work that nobody else is going to do.

One Last Thing

We’re a small foundation working on a big problem. Real-time transit information shouldn’t be a luxury reserved for riders in wealthy cities. The fact that you’re reading this means you’ve already thought about whether your time and skills could contribute to changing that.

The answer is yes. Come say hi on Slack.