7 Tips to Write Flawless Issue Reports on Github

Issue report is like any other text - it can be a piece of text you read and take nothing from or it can fun and rich for the information you really need, for e.g. a job advertisement. You can see:

Do you think better issues is extra work on your side just to make maintainer happier? No! You profit from it.

Writing issue like this takes extra attention, thought and energy. It takes a few weeks to get used to it. So should you write flawless issues in every Github repository you work with? It would probably drain your energy and burn-out into falling back to just poor issue reports.

Personally, I'd focus only on few repositories that matter to me and that I plan to use in the future. The top 3 from top of my head right now would be Symfony, PHP Parser and EasyAdminBundle.

That way you won't burn out writing 10 issues mind-full issues to 10 different projects in a week and projects you love and use daily will grow in time - win-win.

Now you know why and where. I think you're ready for creating the very first flawless issue™:

(The examples will be related to Rector, as I work with it the most lately).

The version of the used project is very important. Maybe you use LTS version, maybe it's legacy already, maybe it's experimental version and it's expected to break. You don't care about this, but it will give maintainer the context of your issue.

How do you find this information quickly?

This one is nice to have if you're into bleeding edge technologies:

I use Rector v0.5.7, and it's still broken on

Test as well. Maybe this issue was reported before 2 days and is already fixed on ? You don't have to read all the past issues - it's a waste of time (maybe there was just PR, or maybe just commit right to the ), just try it:

These reports have exactly 0 added information. By creating an "issue", you've already told the maintainer it's broken.

What should you go for instead? Remove the ambiguous:

I run Rector on [this-code] and I got [this-exception] with [this-exception-message]

These reports could be replaced by black-box style "...on something unknown". 0-value.

Why do we use IDE? Why do traffic lights have colors? What does red in PHPUnit mean?

Colors gives us meta-information, that is processed by other parts of the brain then reading is. That way we understand element with colors faster and easier:

I'm not a dog so I fancy the 1st one.

In the most of Github issues you'll use and syntax highligh:

"What? I thought the more information you'll have, the easier is to fix it." This tip is counter-intuitive. The information is not about quantity, but quality.

The issue report should contain:

At first, it might be hard to figure out what's relevant for the maintainer of that particular project, but based on their feedback you can see it.

Let's look at the code of the previous example - this one has all the relevant information:

This one has duplicated of irrelevant information:

If all the code snippets produce the "Factory return type cannot be resolved" error, use just the first one.

Now the maintainer knows:

Great job! If all the issues were reported like this, the productivity in open-source will sky-rocket (and I mean "Elon Musk" sky-rocket).

The 1st questions that will pop-up in the maintainer's head are "How did you do that?"

Again, think of 4. The smaller the better tip while copy-pasting the .

I installed Rector as dev dependency to composer and run:

Now the maintainer has all the information about your code, your steps that lead to it and the configuration that caused it.

But what do you want?

Here is the syntax becomes very useful:

Having comments is really great. Why?

Which one is preferred?

Last but not least, 1 issue report should talk about 1 issue. Imagine you go for a trip and you talk to your friend how to get there:

Do you have 3 different (see tip #4 again) problems with your code? Create 3 different issues. Don't be afraid, you're not complaining too much.

It's better to have 3 separated issue, that one is easy-pick, 2nd is a question and 3rd need a test case, that all these at once.

Now go out, try, fail and learn :)

Source: Tomasvotruba.cz

Powered by NewsAPI.org

Keywords:

GitHub • Writing • Writing • Information • Employment • Advertising • Employment • GitHub • Repository (version control) • Symfony • PHP • Parsing • Now You Know (Desperate Housewives) • Rector (academia) • Bleeding edge technology • Rector (academia) • Information • Ambiguity • Rector (academia) • Black box • Integrated development environment • Color • PHPUnit • GitHub • Syntax • Information • Information • Software quality • Software project management • Real-time computing • Project management • Feedback • Information • Software bug • Open-source software • Elon Musk • Rector (academia) • Syntax •