- Published on
Ideal Issue Template
- Authors
- Name
- Mrinmay Mukherjee
- @devmrin
Background
As a developer, there are instances when you're assigned an issue to solve.
However, lack of (complete) context leads to solutions that are either -
- incorrect or
- more commonly, incomplete.
Simple Template
Begin with a good title that adheres to [type of issue]: [issue in brief] format.
For example -
Bug: Invalid layout due to horizontal text editor resize
Follow that up with metadata,
global-context: Win10, Chrome 82, etc.
platform-specific: ClientApp or Multiple(ClientApp, AdminApp)
version: X.X.X
Metadata is crucial at times to understand if the problem is simply due to a mismatch in environment, because as we know -
- All browsers aren't created equal.
- Different versions of your app may differ in shipped functionality.
Next,
### Steps to reproduce
1. ...
2. ...
3. ...
...
Followed by,
### The current behavior
1. ...
2. ...
3. ...
...
And lastly,
### The expected behavior
1. ...
2. ...
3. ...
...
I've personally found both - current and expected behavior to be the most significant steps.
As a developer it gives you the confidence to write tests against the expectations and ensures that your solution is complete.
Bonus 🍪
You can always add a screenshot or a recording in addition to the template mentioned above, such that it adds clarity to any of the steps to reproduce current or expected behavior.
Benefits
Simply put, adding steps to an issue makes recreating the issue reliable and deterministic.
It provides any prospective developer (who's assigned the issue) enough context to begin -
- Looking in the right place.
- Asking the right follow-up questions (if needed).