Need clear guidelines for contributing

[bitwiseman]

There's no shortage of people interested in contributing to this project, but there seems to be a shortage of bandwidth on the part of the project owners to review contributions.

It would help contributors and owners if we had a document describing the happy path for contributing: how to structure contributions such that owners can most easily review them and what time frame to expect for feedback and resolution.

This is probably best done as a CONTRIBUTING.md since it changes will need to be reviewed by project owners.

Questions that could be answered in this document:

• I think I've found an bug and I want to file an issue. What information should I include?
• I want to request a feature or change in behavior. What information should I include?
• I've filed an issue (feature or bug). Now what? Is there some process by which it gets reviewed and approved?
• Is there anyway to get an issue important to me fixed quicker?
• I didn't read this, and skipped straight to submitting a pull request with code I want to get merged in, was that a mistake? Should I go back and file a separate issue per the guidelines above?
• I've want to help out by fixing an existing issue. How do I pick which issue to fix? How do I know which ones are important?
• I have fixed an issue and want to submit a pull request. What needs to be included in a good pull request?
• Do I really have to include tests for my fix?
• What coding style guidelines do should I follow?
• I've filed a pull request, but no one seems to be looking at it. Did I do something wrong?

[tj]

most people don't really follow them I find anyway :s from what I've seen most people don't even look at the author's code and attempt to match style etc, shouldn't need a guide for that. I definitely have a lot to go through haha but I'll try and cruise through most of those tomorrow

[bitwiseman]

I'm not sure I understand your response. Are you going to create guidelines or you're not? If you're saying you are going to, I could save you some time and write something up and then you can correct it or tell me what to change.

[tj]

nope, I haven't seen anyone successfully employee guidelines so I think it would be wasted effort personally, there's almost never a pull-request that I don't want to manually massage a bit anyway, it takes more time to walk people through it

[bitwiseman]

Ah, this explains why 80% of the commits are authored by you. 😄

With guidelines you don't have to walk people through it. You set expectations on both sides of the equation. It doesn't have to be heavy, just a set of outer bounds. When people go outside that you point them back to the guidelines, and you get to focus more of your time on fixes and enhancements that meet a min bar for clarity and stability and are thus is closer to being ready to merge.

🤷 You're the boss, I'm just looking for ways to make contributing easier for everyone involved.

[tj]

well I use --author to assign the original :D

most of them are pretty clear yes or no pull-requests I just need to go through them, for the ones that are accepted it goes beyond anything I could explain in a guide really, even just simple things like where I would prefer the function to be defined etc, can't really outline that sort of thing

[boneskull]

I definitely look at a CONTRIBUTING.md when writing a PR for any project that has it. I think this is worth doing, but best to keep it short + sweet.

[jbnicolai]

Agreed. Especially since Github now links to it when creating a pull-request for projects that have a CONTRIBUTION.md in the project root.