Logging issues (or defects) on your project is an inevitability. Unfortunately, so are the hassles that come with improperly logged issues.
Here is a quick guide to help you log your issue in a manner that helps the recipient of the issue to work most efficiently and reduces any back and forth that might waste your time.
Sure, it is reasonable that when you say "[X] is broken" that the recipient of your issue will know exactly what your talking about. That's not the case though.
When filing your issue, assume that the recipient knows nothing about what you're talking about. There is no such thing as too many details when filing your issue.
"[X] doesn't look right" is a bad title when creating your issue. The title should be as descriptive as possible. It should be so descriptive that the recipient should be able to pick up the gist of the issue from the title itself.
The blue widget on the contact page has white space issues
Clicking on "Create" throws a 500 error
The blue muppet should be green
Even the simplest of issues should have an overly descriptive description. Again, there is no such thing as too much information. A well logged issue will include the location of the issue, steps to reproduce the issue (only needed if more complex), and what the desired outcome of the issue is.
On the contact page, I was expecting the blue widget to have less white space.
Can we tighten up the spacing between the blocks in the blue widget?
I tried to create a new recipe, but I am getting the attached error.
Steps to reproduce:
- Sign in to the site
- Click the "Create" button on your dashboard
- See attached 500 error
Please fix the 500 error.
The blue muppet on the muppet details page is green.
Steps to reproduce:
- Go to muppet details page
- See blue muppet in the leaderboard
Can you make the blue muppet green per the mockup from August 10, 2012?
If the issue that you are logging is the result of a big error. The error should be attached to your issue via a text file. Copy the error and paste it into your favorite text editor (Notepad, not MS Word). Once you have a file, attach it to your issue as a file.
You should try to include screenshots for all logged issues, but it is required to file an issue with a screenshot if the issue is related to the styling of the page.
When taking a screenshot, do not paste the screenshot into MS Word or Powerpoint. This causes the screenshot to be illegible to the recipient and they will simply ask you for another.
On a Mac you can take a screenshot with CMD+SHIFT+4. This will put a screenshot on your desktop which can easily be uploaded directly.
On Windows machines, see this.
Once the recipient of the issue has fixed the issue and you have verified that the reported issue is fixed, the issue is closed. If you have related issues, or a new issue was created in the fix, you must open a new issue. This will increase the ticket count, but it helps work to happen most efficiently.
If you follow these steps for the issues that you create, you can help everyone work more efficiently and save yourself the headache of passing issues back and forth.
If you have feedback about this site, feel free to log an issue, or fork the repository and submit a pull request.