Add CONTRIBUTING.md

[andyjansson]

Anything I left out or should change?

[ai]

I am not a big fan of copy-pasting the same CONTRIBUTING.md from one project to another.

It is much better to write specific help for this project. Right now ost of the recommendations are not clear (like what exactly is ”a clear and descriptive title”).

It is great that you mentioned PostCSS chat. But I suggest to:

1. In Reporting Bugs ask to post input CSS, output CSS and expected CSS if postcss-size generate something wrong. If a user has an issue, ask them to post the stack trace.
2. In Requesting Enhancements ask for input CSS, output CSS and expected CSS (and optional use case).
3. In Submitting Pull Requests ask only for tests and use cases for this changes.

[andyjansson]

I am not a big fan of copy-pasting the same CONTRIBUTING.md from one project to another.

Copy-pasting? I spent a good while typing all of that together. I did refer to other projects for inspiration, but it's very much an original work.

In Reporting Bugs ask to post input CSS, output CSS and expected CSS if postcss-size generate something wrong. If a user has an issue, ask them to post the stack trace.

It does:

 * Summarize the problem you are having. 
...
* Provide steps to reproduce the problem.
* Describe what behavior you expected to see.

In Submitting Pull Requests ask only for tests and use cases for this changes.

Why? Listing issues is important for cross-linking issues and PRs.

[ai]

I spent a good while typing all of that together. I did refer to other projects for inspiration, but it's very much an original work.

Sorry. I thought it was the same CONTRIBUTING.md as other projects copy-pasting. My mistake.

But it means, that the rules are not project-specific.

It does

Nope, since “Summarize the problem you are having” you do not describe how to summarize it. There are multiple ways to do it. And new developer could not know any of this way. This is why strict recommendations are better.

Check out PostCSS plugin guidelines. Every rule is clear and strict.

Why? Listing issues is important for cross-linking issues and PRs.

If you want to force developers to create an issue for any new PR, you can keep it.

But I think sending PR should be easy as possible (since PRs are rare).

[andyjansson]

Nope, since “Summarize the problem you are having” you do not describe how to summarize it. There are multiple ways to do it. And new developer could not know any of this way. This is why strict recommendations are better.

I disagree with that. I don't think I need to outline every way the package can possibly fail and provide guidelines for each case. I think the generic guidelines provided are sufficient for people to infer meaning and provide meaningful feedback. People aren't stupid.

[ai]

You can your way too, of course. It is your repository.

Core question here is what you try achieve? Be in trend? Help new developers without any knowledge of open source? Reduce PR code reviews and issue comments?

[andyjansson]

Core question here is what you try achieve

I believe this was answered in the document:

On questions:

leave us available to solve issues and make the product better.

On bugs:

help maintainers reproduce the problem

On PRs:

• give feedback early on before significant effort has been put into the endevour.
• align your contribution with ongoing efforts.
• make sure that there's no ongoing effort into the issue already.

[ai]

OK. So I will rephrase it to “reduce maintainer time for issues and PRs”.

Why do you think:

1. Contributor without good experience in open source will be able to understand what is “clear description”?
2. Contributor with good experience in open source will be able to understand what is required limit in clear description? Some contributors spend hour for preparing issue. Other spend 5 minutes and think that their 1 sentence description is clear too.

Also, sorry for strict and aggressive style of first comments. (It is culture difference, in Russia we must to be always strict)