In the last couple of months, I have been working on a "new" open source project - an open source enterprise Stripe App!
How can I improve collaboration when writing issues/tickets? Read more to learn my thoughts
The importance of writing good issue tickets on open source projects
If you're working on an open source project (on github) with other people spread across the internet, it's important to write clear and concise issue tickets.
This way, everyone knows what needs to be done and no one wastes time doing things that aren't necessary.
There are a few different ways to go about writing an issue ticket.
The first one: use a template.
Issue templates for open source projects
You can find heaps of github issue templates online or in various text editors (like VS Code). Using a template ensures that you include all ✨ the important information in your ticket.✨
However, templates can be a little dull. You might have to customize templates to match the type of project you're working on, so choose wisely.
Another way to write an issue ticket is to simply include a title and brief description of the problem. This is usually sufficient for small issues. However, for larger issues, it's often helpful to include more information such as screenshots, steps to reproduce the problem, etc.
In general, it's best to err on the side of too much information rather than too little. That way, whoever is assigned the task can quickly understand the problem and get started on a fix.
How to write a good issue ticket on an open source project
There are a few best practices to follow. First, be sure to include clear and concise titles and descriptions.
If your issue is related to a specific piece of code, include that in the ticket as well. It's also helpful to include:
- logs
- screenshots
- .. or videos if applicable.
Finally, be sure to tag the issue (do NOT tag the members of the project directly) so you can categorize appropriately the issue.
Tips for writing a good issue
If you're new to open source, collaboration, or just want to improve your issue-reporting skills, read on for some tips on how to write a good issue ticket.
1️⃣ First, be sure to include a clear and concise summary of the issue in the title. This will help others quickly understand what the problem is and whether they can help.
2️⃣ Next, provide as much detail as possible in the body of the issue. Include screenshots or screencasts if they would be helpful in understanding the problem.
(Speaking of screencasts - my friend Ian is working on making screencasts awesome at replayable.io if you want to give him some love - I would be appreciative of your time)
👉 And be sure to include any relevant error messages or logs.
3️⃣ Finally, if you have any ideas about how to fix the issue, feel free to include them in the issue ticket. It might help shape the solution, in a form or another - by the way, this is totally optional!
Hope this helps, I've been using this method for my own work on Github and I think it has been working out pretty well!
Top comments (0)