Sometimes, developers mess up. We don’t mean to do it, but sometimes, our code is exposed to situations we didn’t anticipate. The best we can do when that happens is to fix our mistakes and learn from it. Some of us even try to find ways to make sure this doesn’t happen again. How? Document our mistakes and make sure developers can discover them in the future.
Over time, these learnings grow into an unmanageable collection of documents. The effectiveness of these documents decreases because no developer writes code with multiple pages full of caveats open in a separate window. We’ve heard from our customers that it would be great if there was an easy way to scan and access a checklist that is available during development and pull request reviews.
Many projects have solved this problem by having a CONTRIBUTING.md file in their repository, which not only mentions how to contribute to that repository but also lists the things to look out for. A good CONTRIBUTING.md file serves as a helpful checklist during development. It would be even better if we could somehow enforce that during the review process.
So, during an internal hackathon, I built an add-on that attempts to do exactly that. The “pull request guidelines” add-on parses the CONTRIBUTING.md file in your repository and summarizes it in the form of an easy-to-scan checklist. It then makes the checklist accessible in the pull request itself, so both the author and the reviewer can easily go over the list of guidelines. The “pull request guidelines” add-on also makes it super easy to turn these guidelines into actionable tasks.
This add-on was a result of a couple of weeks of work, so it’s not quite done yet. But that shouldn’t stop you from trying it out. Check out the add-on page to learn more, and if you just want to install the add-on, click the button below: