CONTRIBUTING.rst should specify how to attach a file

[pinobatch]

CONTRIBUTING.rst states that one of the steps in reporting a bug is "If there is a piece of code that triggers the bug, try to reduce it to the smallest file you can." I take this to mean what Stack Overflow calls a minimal complete verifiable example (MCVE). It doesn't state how to attach that file to the issue.

In #1146, I uploaded the relevant files as attachments to the issue. One user told me that this caused an undue inconvenience for the user because the web browser would download the file to the device's Downloads folder instead of displaying it. The user recommended that I create a GitHub Gist instead because the reader can view it in a web browser without leaving a copy in a Downloads folder that the reader has to remember to delete later. The problem I have with a gist is that because it appears as an HTML document, I feel obligated to provide context for people who happen upon the gist through an inbound link, such as by citing the related issue. But I can't cite the related issue because it doesn't have an issue number until I create it.

Another option, as used on Stack Overflow, is to write each file inline in the opening comment in a triple-grave-accent-delimited code block

like this

Please specify in CONTRIBUTING.rst how people reporting issues ought to provide related files going forward.

[Rangi42]

I'm not sure if this level of spelling things out would be appropriate. People can use inline code blocks, Pastebins, uploaded files, linked gists, links to their own repos, whatever makes sense in context of how much they have to share. I don't think the rgbds maintainers as a whole (un)endorse files completely.

[aaaaaa123456789]

In the end, this is a non-issue — if someone has trouble with what you upload (as I did that time you mention), they can just ask you to upload it some other way (as I did). It's no big deal!

[ISSOtm]

"Best/reasonable effort" does apply, and worst case, we have nothing against a bit of iteration. Using the ostensible GitHub feature makes sense; see also what ax6 said above.

(As for Gists specifically, it appears that the description can be written a posteriori, and it should be fine to leave it blank for a few hours, heck even a few days, while writing the issue description.)

More generally, Pino, it seems to me as if you're putting too much pressure on yourself to get things perfectly right out of the gate, and I fear that might be unhealthy. I don't know about other places you interact with, but I can assure you that for all GBDev-related projects, we can put up with far more "iteration" than what you are already doing.

tl;dr what you are currently doing is fine, don't worry.