· Ahmed Hossam

Getting Started with Maglev: Tips for New Contributors

I’m Ahmed Hossam, a Software Engineer at OTSF and a former contributor through GSoC 2024. For anyone interested in contributing to Maglev (the new Go-based server replacing the current Java-based OneBusAway server), I wanted to share some tips and resources that might help you get started.

Understand GTFS Static Data

Before writing any code, it’s very important to understand GTFS Static data and how it is used. GTFS Static describes the scheduled transit system: routes, stops, and trips.

Things worth understanding:

  • What each file represents (stops.txt, trips.txt, stop_times.txt, routes.txt, etc.)
  • How trips are connected to routes and stops
  • How blocks, services, and calendars work
  • How the static data is used by the server

Resources:

Understand GTFS-Realtime

GTFS-RT provides live updates about the transit system. The main realtime feeds are:

  • Trip Updates — delays, cancellations, and arrival predictions
  • Vehicle Positions — where buses and trains currently are
  • Service Alerts — disruptions or service changes

It’s very important to understand how realtime data maps to the static GTFS trips.

Resources:

Study the Existing Java Implementation

Maglev is a migration from the existing Java server, so many behaviors already exist there. A helpful strategy is:

  1. Look at the Java implementation
  2. Try to understand the logic
  3. Then figure out how it should be implemented in Go

This is something I still do today. Even after working on the project for a while, I keep discovering new details about how things work. Understanding the existing behavior helps you know why something works a certain way, not just how to implement it.

There is also a great way to explore the Java codebase using AI. DeepWiki provides a RAG (retrieval-augmented generation) interface for open-source GitHub repositories, so you can ask an LLM questions about the indexed code. This was suggested to me by Aaron, the Executive Director, and it can be very helpful when trying to understand parts of the Java server.

Be Thoughtful About Using AI

Please avoid opening issues, PRs, or writing code purely generated by AI without understanding the problem. AI is a great tool (I use it too), but there is a big difference between using AI when you understand the system and using AI when you don’t understand the context.

Even when using AI, mistakes happen. I make mistakes sometimes as well, and that’s normal. The important part is understanding the system well enough to review and validate what AI suggests. Before contributing, try to understand at least roughly 70% of the problem, including the GTFS static data, the GTFS-RT data, and the system behavior. This will save your time and the maintainers’ time.

Also, remember that your chances of joining GSoC are not based on the number of PRs you open or the number of lines of code you write. What really matters is your understanding of the system, the quality of your contributions, and your ability to explain the problem and the solution. Quality and understanding are always more valuable than quantity.

(See also: Our Policy on AI-Generated Contributions)

Test Your Changes and Compare with the Java Server

When you open a PR, please make sure you test your changes and verify the behavior. A good approach is to fetch the API responses from the Go server and compare them with the production Java server. Since Maglev is a migration from the Java implementation, the responses should generally match.

However, do not migrate behavior blindly. The Java server can also contain bugs, so if something looks incorrect, try to investigate and understand the root cause instead of copying the behavior directly.

There is also a tool I built that I personally use almost every day to help with this: maglev-validator. This tool compares Maglev (Go) responses against the Java server and highlights the differences. It also allows you to:

  • Include production GTFS-RT data
  • Inspect differences in API responses
  • Inspect the GTFS Static file
  • Better understand how the system works

It has helped me a lot in understanding the system and developing features for Maglev, so it might be useful for other contributors as well.

Questions and Support

If you have questions about GTFS, GTFS-Realtime, Maglev, or the migration process, feel free to ask publicly in the Slack channel or contact me directly. There are many helpful people in the community who are happy to assist.

Thanks to everyone contributing to the project. Your work really makes a difference!