Matomo In Depth

Using GitHub Issues

Using GitHub Issues

Starting to work on an issue

  • Assign yourself so it's clear to everyone you will be working on this issue. It also helps yourself to keep track of your current work.
  • If you stop working on this issue for some reason, and you won't continue working on this issue, then unassign yourself and leave a comment about any kind of useful information and ideally why you stopped working on it.
  • Read the issue description carefully (best to read it twice) and make sure you fully understand the issue. If anything is unclear, comment in the issue and ask for more information.
  • If the issue is a bit bigger or there are many ways to solve this (from a UX or from a code perspective) and it's not clear which way to go be great to comment the findings and mentions this in a comment and seek the feedback from others. It may also help additionally going on a call with someone if it's not easy, as sometimes talking about things and discussing something with another human can help make things more clear.
  • When working on an issue that is likely to take longer than say 4 days because it is some complex refactoring or work, then it might be good to write first some concept and double check the concept is a good idea before doing any work on it.

Commenting on issues

  • Anything we comment on GitHub is publicly available and affects our image etc. Not just to this user, but also every other user who will read this comment over time.
  • Every comment is the possibility to turn a user into a fan
  • We have replied probably thousands of times, and then it's easy to just quickly ask or comment on something, but remember it might be the first time for the other person who created an issue. The problem might be very important for them, they potentially took some time to create the issue etc and a good response will make all the difference to them. It's hard to always incorporate below things, but we try our best as it doesn't even really take more of our time to add a few extra words of greetings, appreciation, empathy, etc.
  • Ideally, when commenting the first time to an issue, we start with something like "Hi, @username" or "Thanks @username".
  • When a user creates a feature request or bug report we thank them for taking the time to create this issue.
    • Example: Thanks for creating the issue @username . Very appreciated. I've just installed Windows and was able to reproduce it...
  • When it is a bug, and we can reproduce it, ideally we acknowledge the problem and could even say "sorry about this" or "must be painful" or similar where appropriate.
    • Example: Hi @username sorry about this. I'll do my best, so we can hopefully get things sorted and working for you.
  • If we likely won't work on the issue anytime soon, we can invite users to create a pull request should they have technical knowledge.
    • Example: Todo
  • If an issue is actually a question, we close the issue and refer nicely to the Forum as the GitHub repo is not a place for questions.
    • Example: Todo
  • If we can invite the user to collaborate, that is always great too
    • Example: The existing WP-Matomo will be slightly renamed soon to WP-Matomo Integration (WP-Piwik) and we'll also try to further reduce the confusion there. If you have any ideas or thoughts on namings and how they could be better differentiated, please let us know. Very appreciated your feedback.
  • We will try to close issues sometimes when we think we answered it or the issue is done. We mention though that we're always happy to reopen the issue.
    • Example: ... answer... I'll close the issue now. Should this not help or if I understood something wrong feel free to comment, and we'll be happy to reopen the issue and investigate further.
  • If we helped them, we can also say things like: "Awesome, I'm glad it works now for you."
  • If we feel that we answered an issue and an FAQ could prevent the same from being asked again (or next time someone asks this we can simply send that link), then we aim to write an FAQ.
  • Remember when replying
    • Be polite and respectful.
    • Acknowledge the time that the person has already invested.
    • Acknowledge the time that you're asking the person to additionally invest.
    • Be thankful.
    • Focus on the work.

Collaborative software development is an inherently social process, and there's a natural human tendency to treat the contribution and the contributor interchangeably. It should go without saying, but it's important to keep the focus on the work itself, especially when delivering critical feedback.