How to Raise a Github Issue

Our beloved devs need to have a lot of skills. Not only do we ask them to be ruby, rails, angular, css, postgres, git, js, active record blah blah blah super stars… but they need to know the inside outs of how OFN works, basically from day one. Let’s make life as easy as possible for them! Let’s create the perfect issues…

Please add everything you can think of that defines good issue specification!

Is Github the right place?
Github is all about technical details. If you want/need to discuss a bit more, then Discourse is the right place.
Any discussions that involve understanding the nature of the solution and how it might work from the user perspective belong to Discourse as well.
New features are first discussed on Discourse to gather as many perspectives as possible. Once it is is clearly specified, the technical implementation is usually divided into multiple Github issues.

All Github issues should always:

  • Include screenshots of the issue happening. Even if you think you’ve described where it is happening, a screen shot is worth a thousand words.
  • Add any labels appropriate.
  • Tag people if you want them to respond!!
  • Keep issues simple. We shouldn’t need to discuss more than technical aspects of a solution on Github. Discourse is the place for discussion spec on a more general level.
  • Open Discourse posts for bigger discussions that involve understanding the nature of the solution and how it might work from the user perspective.

If the issue is about the way the UI renders:

  • It is important to know if this is happening in all browsers, versions, systems. If you can’t test this make sure you specify device, operating system and browser with version.
    Good examples: #1418 #1543

If the issue is a bug in the functionality:

  • Include as much information as you possibly can that describes when the bug occurs.
  • If the issue is reported by a user always recreate the issue and describe step by step how you recreated it so that we can be sure if it is sporadic or conditional. This will also help you to indicate priority.
    Good Examples:

If the issue is a new feature:

  • Discuss the new feature with the global community first to develop and agree a Requirements Specification. If this is a new feature and you haven’t done this it probably isn’t ready for Github.
  • Github issues on the new feature will most likely be many bite sized chunks. Wrap the issues for the new feature in an Epic and/or add them to a specially named Project as a way to capture and track the whole feature.
    Good Examples:
2 Likes

GitHub offers a nice tool to “enforce” or suggest issues and PRs descriptions. They call it templates:

1 Like

Yay, great post. The first list mixes the concerns of how to write an issue and when Discourse is better. Maybe we start like this:

Is Github the right place?

  • Github is all about technical details. If you want to discuss a bit more, then Discourse is the right place.
  • Any discussions that involve understanding the nature of the solution and how it might work from the user perspective belong to Discourse as well.
  • New features are first discussed on Discourse to gather as many perspectives as possible. Once it is is clearly specified, the technical implementation is usually divided into multiple Github issues.

All Github issues should always

  • Include screenshots…
1 Like