The Apache Beam community recently migrated to GitHub Issues after years of using Jira as our issue tracker. This post details why we made the move, how we did it, and how to decide if migrating is appropriate for your project.
Why We Made the Move
The move to Github Issues was driven by a number of factors, but by far the largest was the desire to lower the bar for community engagement. Previously, to open an issue users had to:
1) Read through our getting started docs on the Beam website
2) Make a Jira account
3) Email the large Beam dev@ mailing list asking for Jira contributor permissions
4) Then, and only then, open a Jira ticket
In contrast, since most of our users already have a GitHub account and some familiarity with how Issues work, they now just need to open the ticket without asking anyone else for permission, dramatically lowering the bar of entry to participate in the Apache Beam project. While it's still early, we've already seen some early returns; anecdotally, in the Beam Go SDK (where I spend most of my time), we had three new contributors open their first issue in the first two weeks after the migration, after going months without adding any new Go contributors before the migration. Even better, that led to three quality PRs from one of the new contributors! Other regular contributors have described similar experiences in other parts of the codebase.
Some of the other benefits of moving to Issues include:
- Custom Issue templates
- Extensive existing and customizable automation via GitHub Actions
- Effortless linking between Issues and PRs
- Markdown everywhere
- Unified Search for Issues and PRs
How We Made the Move
Since we had a huge backlog of active Jiras with valuable context, we decided to port all of them to Issues. To do this, we built our own migration script which copied over the issue, reporter, assignee, and some selected metadata as labels. Since Jira has a custom formatting syntax, this also required building in format translation to maintain things like code blocks and bullet points. All of this is open sourced at https://github.com/google/jira-to-issues.
Other than that translation work for the migration script, migrating was surprisingly painless; aside from documentation updates and removing outdated automation, the only changes needed were adding some issue templates and actions to help keep the quality of Issues high.
Should You Make the Move?
I would highly recommend moving to GitHub Issues if you are an Open Source project interested in building a larger and more accessible community; Github is where Open Source developers live and are most comfortable, and migrating to Issues can significantly reduce the friction of joining a project. If you're not looking to build a community, moving to Issues may be more trouble than it's worth; while Issues certainly still has its advantages, its strength is the way it enables communities to grow and build together.
Lastly, if you're looking to try out Issues while getting involved in a growing Open Source community, then come check out Beam! We're building SDKs and Runners to express parallelizable data pipelines in a variety of languages for a number of different execution environments (Flink, Spark, Dataflow, Ray, Dask, and more); so far we have SDKs in Java, Python, Go, SQL, and TypeScript, but we're always looking to support more languages. (Here’s looking at you, Rustaceans.) If any of that sounds interesting, come take a look at our starter issues - https://github.com/apache/beam/contribute. We'd love to welcome you to the Beam community!
Top comments (0)