Klaxon is open source software built in the newsroom of The Marshall Project, a nonprofit investigative news organization covering the American criminal justice system. It was created by a team of three—Ivar Vong, Andy Rossback and Tom Meagher—and has been maintained by Gabe Isman and Ryan Murphy in the years since then. It is subject to the kind of shortcomings any young, small side project might encounter. It may break unexpectedly. It may miss a change in a website, or an email might not fire off correctly. Still, we’ve found it immensely useful in our daily reporting. We want other journalists to benefit from Klaxon and to help us improve it, but keep these caveats in mind and use it at your own risk.
When you spot the inevitable bug, please let us know. And if you’d like to help us make this better, or add new functionality to it, we’d love to have your help.
There are several ways you can help improve Klaxon, even if you’re not a coder or you’ve never contributed to an open source project before. You can:
Help us spot bugs, including typos, and let us know by filing an issue in GitHub. If you’ve never used GitHub, don’t worry. Here’s a really good, quick tutorial about discussing projects in GitHub Issues. Even if you’re an experienced GitHub user, this blog post provides some great advice on the best practices of creating an issue.
Help test the web interface, sharing feedback with us directly in an email or in a GitHub issue. Help prioritize new features for the community to work on together next, by commenting on ones you like in our GitHub issues.
We’re excited about other journalist-developers contributing code to support the project.
If you want to contribute, start by reviewing this advice inspired by this post on the Codacy blog and Shauna Gordon-McKeon’s PyCon 2015 talk. Read the documentation in our GitHub repo, particularly this CONTRIBUTING.md file and our Code of Conduct. You’re now ready to engage with the community by commenting on issues and participating in the process.
Look for issues in Klaxon’s GitHub repo tagged "help wanted" or “first-timer-friendly”. Create a new branch for your feature, write a patch and send a pull request to us on GitHub.
Klaxon now supports GitHub Codespaces, making it possible to work on the codebase without setting it up on your local computer.
If you want to get Klaxon running locally follow these directions.
We should acknowledge your patch and respond with questions or comments. We expect that you’ll remain engaged with the issue, responding to our questions in a timely manner and iterating on the code until the patch is merged or otherwise closed.
One of the things we’re most excited about as we release Klaxon is seeing how other newsrooms put it to use. We’ll be eager to hear from you about your experiences with the tool. There are several ways we can discuss this together. You can email us directly at [email protected]. We also have a Google Group email list where Klaxon users and developers working on the project can talk. Users can ask questions of one another, and contributors can discuss changes to the code and adding new functionality. Finally, you can always open or comment on an item in our GitHub repo’s issue tracker.