Two GitHub features that make bug reporting and triaging easier than ever
At Ariga, our software solution is heavily built on top of ent. Ent is a simple, yet powerful entity framework (ORM) for Go, that makes it easy to build and maintain applications with large data-models. Ent makes it possible to define any data model or graph-structure in Go code easily. Ent generates an idiomatic and statically-typed API for working with databases that keeps Go developers productive and happy. As we rely on Ent for building our Operational Data Graph platform, we are deeply invested in the project and are committed to making it and its community successful.
In this blog post, we would like to share with you our success story using two GitHub tools, template repositories and Codespaces, that help us maintain Ent by improving contributor productivity and the overall velocity of the project.
Our Story
As a project maintainer, it is in your best interest to ensure that your users are happy and receiving the help they need. By addressing bug reports and solving them, you are able to improve the quality of the project as well as assist users. The optimal way to receive a bug report is in the form of a reproducible example. Generally, this requires receiving code that is runnable in order to see a live example of the problem.
On GitHub, it is common practice to ask the user to open an issue and provide a temporary repository with the code to reproduce the bug. In Ent, there is a special bug reporting issue template that guides the user on how to properly describe the problem. Using the issue template makes the project maintainer’s life easy by ensuring that each issue includes all the necessary information and is written in an organized manner.
Once the project maintainer gets a hold of the repository, they can locally clone it and start debugging, rather than create a new project from scratch to try and reproduce the issue. However, this method can be risky. Although most users are friendly and don’t have bad intentions – you can never trust too easily. You don’t know what’s in the code you are about to execute and what harm it may do. It is always possible to check the code, or to run it in an isolated environment, yet it takes time and effort to go to these lengths to ensure your safety.
In August 2021, GitHub released a new feature, Codespaces. GitHub Codespaces is a tool that offers cloud-powered shared development environments right from within a web browser, giving access to an entire Visual Studio Code experience. Directly from any repository you are able to run your code without any installations, as if you were fully configured and running on your own local machine.
Soon after Codespaces was released, Ariel (Ariga’s co-founder and Ent’s creator) decided to give it a try. He opened a repository provided by a user, intending to debug an issue, straight in Codespaces (you can view the issue here). With a click of a button, without any prior setup needed, he was in a completely ready-to-go environment and was able to start debugging right away! Within a minute, the bug was triaged and Ariel was able to get back to the user with the answer. This is any project maintainer’s dream! You want to be able to address as many issues as possible, diligently, and in a timely manner, without having to risk your own safety in the process.
Taking this idea a step further, I thought about using template repositories to refine bug reporting even more. Template repositories is a feature designed to “make boilerplate code management and distribution a first-class citizen on GitHub”. These repositories are used as templates across multiple projects, for simple code reuse and enable developers to easily create new repositories with the same directory structure, branches and files. Generally, template repositories are used as a way to kickstart projects quickly, however the Ent project came up with another use for them.
Ent launched the new ent/bug template repository. This template has Ent pre-installed, a basic user schema, and test connections to different databases. Now users can easily create a new repository from the bug template and add in their code. This way, users can share the necessary code for reproducing the bug, without having to spend much time on setting up a new project.
By utilizing the strengths of both Codespaces and template repositories, we have made both bug reporting and triaging much easier tasks. Using both of these tools is a win-win situation for project maintainers and the users alike. Project maintainers can now significantly cut down the time required for setting up environments to triage bugs, making the entire process much smoother, faster and safer. Similarly, users now have the ability to save time and effort and are able to consistently provide reproducible bug reports.
We highly encourage you to try using these tools in your own project and see what life changers they are!
Feel free to find me on the the #ent channel on the Gophers slack workspace if you want to discuss this topic or ask any further questions, I’d love to hear from you!