Add CONTRIBUTING.md

[Umcaruje]

The reasoning behind this: We get an awful lot of bad issues and we need guidelines for them.

Why is this commited in the source and not in the wiki?
So any user that wants to submit an issue gets presented with this info box that leads to this file.

A more read-friendly version: https://github.com/Umcaruje/lmms/wiki/CONTRIBUTING.md

[StakeoutPunch]

+10000000

Please.

[Wallacoloo]

Honestly, I would have just had Contributing.md link to the Reporting Issues Wiki page. If you think it's important to have that information in the actual Contributing.md document, then after this PR we should remove the wiki page and have the wiki page link to contributing.md to avoid duplication or contradictions.

Can people without push access to the repository tag their issues? If not, then I think the labels section should be moved out of this document & linked to. If the purpose of Contributing.md is to get people to read something before posting issues, then it should only describe how to post a ticket and provide outgoing links for topics that are related, but not directly applicable. Otherwise, the page gets lengthy and people will skim/ignore it.

Along those lines, I think you could be a bit more concise in areas. Why this:

Your issue should have steps to reproduce the issue. When writing the steps,

• You should use lists.
• Lists are much more readable.

1. There are also numbered lists.
2. You can use them too, if you fancy that kind of thing.

instead of:

You should include steps to reproduce the issue and format them using a numbered or bulleted list.

That conveys the same information in a quarter of the space, increasing the chance people will actually read it.

Also, I think the value in linking to an example of a properly written ticket is huge. The wiki uses #1875.

[Umcaruje]

Honestly, I would have just had Contributing.md link to the Reporting Issues Wiki page

I did not even know that that page exists. I still think contributing.md should be the place for this. The wiki page can link to it.

If not, then I think the labels section should be moved out of this document & linked to

True, will fix

[tresf]

I would have just had Contributing.md link to the Reporting Issues Wiki page

Agreed. Less documentation in our source. 👍

[Umcaruje]

I removed the labels section and linked to the wiki articles. I also added the reference to the proper bug report.

I strongly disagree that the contributing.md file should just link to a wiki article. When you present people with a link to something which has another link that leads to something, there is really small chance people will click that 2nd link.

[tresf]

When you present people with a link to something which has another link that leads to something, there is really small chance people will click that 2nd link.

Doesn't this describe our download link? 😉

[Umcaruje]

Doesn't this describe our download link? 😉

It doesn't, because you don't perceive the download button as a link to something. Its an action that will download the software to your PC.

The average user of this issue tracker will never bother to click two links just to read something.

[tresf]

The average user of this issue tracker will never bother to click two links just to read something.

That is speculative and the file as noted has redundancies with our wiki. In my opinion, directions for quality control in our bug tracker have no place under our source tree. GitHub should allow linking to a wiki and perhaps we should request the enhancement of GitHub rather than placing a long wiki article into our source code?

[tresf]

So I'd like to beat this topic up a bit...

You state "The average user of this issue tracker will never bother to click two links just to read something" but the article is long and there's a good chance most people won't read this whole thing anyway (e.g. TL;DR)...

Can we consider a bulled-linked-version (best of both worlds perhaps)? That way our rules are short and sweet, but they reference wiki articles that have already been written as the wiki is more suitable for frequent edits, whereas the bulleted listing could remain rather static over time.

For example:

---

Bug Reports

Issues and enhancements must follow these rules

• Search first, then post
• Clean, simple titles
• Exact steps to reproduce
• Version or branch affected
• [...etc]

---

[Wallacoloo]

If done well, I think @tresf's suggestion could work.

[tresf]

@Umcaruje I know there were some thoughts back and forth on this. I still strongly feel we should be careful not to put too much documentation in our code repository.

Since our largest offender was blocked, the quality and frequency of the bug reports seems to have improved, so if you decide this is more work than what it is worth, I'll agree to that too.

[tresf]

Closing for now as our tracker has been much cleaner since we've bumped the offenders. We can reopen it at any time in the future as need warrants it.

[Umcaruje]

I still believe there is a need for this. The amount of non-proper issues hasn't really reduced, and I think this could help out.

Or we could have a template made for our issues: https://help.github.com/articles/creating-an-issue-template-for-your-repository/

Where the user would have blank spaces to fill out his problem.

[tresf]

Or we could have a template made for our issues: https://help.github.com/articles/creating-an-issue-template-for-your-repository/

👍 I like this much more. Most bug trackers I use have this as well.

[tresf]

@Umcaruje can we switch to something like what Homebrew uses? e.g.

ISSUE_TEMPLATE.md, PULL_REQUEST_TEMPLATE.md ...

Examples:
https://github.com/Homebrew/homebrew-core/tree/master/.github

[Umcaruje]

Yeah, that ought to work even better. I'm in the middle of my finals atm though, so I won't be able to work on anything LMMS related this week.

…

-Uroš|Umcaruje

On 5 February 2017 at 19:46, Tres Finocchiaro ***@***.***> wrote: @Umcaruje <https://github.com/Umcaruje> can we switch to something like what Homebrew uses? e.g. ISSUE_TEMPLATE.md, PULL_REQUEST_TEMPLATE.md ... Examples: https://github.com/Homebrew/homebrew-core/tree/master/.github — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2348 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AF_bPXlDEc_mKFMc-XlSMBVIVFicPzwIks5rZhkJgaJpZM4F8dum> .

[jasp00]

Were some users suggesting these templates already? E.g., @musikBear at #3321 (comment).

[tresf]

@Umcaruje can we switch to something like what Homebrew uses? e.g.

ISSUE_TEMPLATE.md, PULL_REQUEST_TEMPLATE.md ...

Yeah, that ought to work even better. I'm in the middle of my finals atm
though, so I won't be able to work on anything LMMS related this week.

Sounds like this will be superseded. Please commit the new ISSUE_TEMPLATE.md if you think it's needed.

Here's an example of one I have on another project...