Clarify bug reporting with regards to providing a pdf #5963
Conversation
|
The main issue is probably that people often times don't bother reading CONTRIBUTING.md at all (there's a link to it on the "New Issue" page, so it should be hard to miss). |
| @@ -2,6 +2,8 @@ | |||
|
|
|||
| The issues are used to track both bugs filed by users and specific work items for developers. Try to file one issue per problem observed. Please specify a valid title (e.g. "Glyph spacing is incorrect" instead of "PDF.js does not work") and provide more details about the issue: link to the PDF, location in the PDF, screenshot, browser version, operating system, PDF.js version and JavaScript console warning/error messages. Issues that do not have enough details provided will be closed as invalid/incomplete. | |||
|
|
|||
| We understand that many PDFs contain sensitive information, however having a PDF to reproduce and test is essential to resolving the issue and building regression testing. If possible try creating a reduced example exhibiting the problem but not containing sensitive data. Also small PDFs are best suited for our regression testing. If an important issue only shows on sensitive PDFs, contributors might be willing to accept these PDFs via a secure exchange. If a PDF cannot be provided, the issue is most likely to be closed. | |||
|
|
|||
There was a problem hiding this comment.
Perhaps this entire section could be highlighted, using e.g. italic or bold text, to draw attention to it?
There was a problem hiding this comment.
as per your initial argument, I don't think that highlighting makes it any better. it is just the long form of "link to pdf required"
|
You are right, once you clicked "New Issue" you should see that link. I thought that however the general readme should provide a bit more guidance on bug reporting in the first place. |
|
I'm fine with this change. I wouldn't highlight it either. Just adding the paragraph already helps I think and making the issue reporting guidelines available from the README should help too. |
CodingFabian
force-pushed
the
enhance-bug-reporting-guide
branch
2 times, most recently
from
7c8e0ba to
04586a0
Compare
CodingFabian
force-pushed
the
enhance-bug-reporting-guide
branch
from
04586a0 to
2175b87
Compare
|
I made it a bit clearer that issues with regards to pdf rendering will be closed if a pdf is not provided. i think thats reasonable with the explanation at hand. |
Clarify bug reporting with regards to providing a pdf
|
Looks good, thanks! |
With respect to many bug reports not providing a PDF, I looked for a possible cause.
What I found is that the actual guidelines for bug reporting are in CONTRIBUTING.md, which is not really linked prominently.
So I decided to put a link to it into the README.md which is rendered by github and clarify the naming of the links.
I remove the style-guide link for brevity, because its only important for contributors which run the contribution workflow, which already talks about linting (and references the style guide)
Most importantly I have added quite a lengthy paragraph about the importance of providing a PDF.