loading...
Cover image for Github Issues: Helping without committing.

Github Issues: Helping without committing.

danmademe profile image Daniel Cherubini ・3 min read

Being an open source maintainer is a rewarding experience, and something everyone should try at least once. You'll meet some amazing people in the community, be inspired and amazed at how people who have never met you will contribute to your idea.

There's lots of positives, since almost always you're doing this as a side project. I'm guessing like most of the open source maintainers, you're kinda pressed for time. Me personally, between work, my daughter, partner, and our serious addiction to TV.. I have very little free time for my open source projects, which is common.

So between midnight and 3am when I normally reserve time for either video games, or responding to github issues and coding, there's a few things you as a open source consumer can do to help both yourself and the project maintainer.

We got some issues...

I feel like when it comes to issues there's three basic kind of reporters

  1. Good information given: stack trace, error messages, and how they got there.
  2. No information given: no stack trace, no error messages, and cryptic issues.
  3. Nothing to do with your code at all: looking for help, (in all the wrong code bases).

For us as maintainers, we want people to use our code, to give us a star, maybe even to tell others about the code. So we're going to help everyone, no matter what the question is about.

What can you do?

It's really quite easy, Github have acknowledged the problems that their issue tracker has, and apparently (read: hopefully) something will be done about this. Til then here's a simple guide.

Ask yourself these questions before posting.

  1. Is this issue I'm having about the code in this repository?
  2. Do I have a stack trace or some kind of error I can paste into the issue?
  3. Am I clear about what is wrong, and what's going on?
  4. Can I explain what I expected to happen and what actually happened?
  5. Did I do a search of the other issues and found nothing?
  6. When was the last commit on this repository?

Now you don't have to do all of those, start from the top and get as many as you can going down. It's really simple.

Some of you may have noticed number 6... You're probably thinking to yourself why? It's simple when you realise that if the dev hasn't looked at this code for a long long time they might have forgotten that this exists, or what the code looks like. Expect them to not get to the answer quickly.

Examples

Let's start with an example of what not to do.. now you've read all this, let's put it in practice.

"sorry, I don't know how to solve the SEO, can you tell me"

I have no real idea of what he is talking about. Since the project he is opening this issue on, has little to do with SEO. So instead I will be forced to solve his issue without knowing what it really is, whilst trying to get information.

Now some good examples

"I am getting the body parser error because express-vue can not find the components. I tried adding a new component to your example vue-example-basic by doing the following:"

app.get('/', (req, res) => {
    res.render('components/index', {
        vue: {
            meta: {
                title: 'foo'
            },
            components:['modal']
        }
    });
});

"and I added a modal.vue inside the components directory. What am I conceptually doing wrong here? Thank you!"

Look, see how different this is? No Stack trace, but he added the Object that caused the error. It's clearly explained and it was solved very fast.

Finally

Not everyone speaks English, and that's cool, I don't think any maintainer cares about that. Just do your best trying to fill as many of those 6 steps as you can, and there won't be any language barrier. Not everyone can wrap their head around new code.. but remember your implementation of our open source package is just as confusing, so please do everything you can to help us help you!

Discussion

pic
Editor guide