Define guidelines for contributing

[matthijskooijman]

Regularly, we get issues and pullrequests which are incomplete, support requests instead of bugs, with poor commit messages or commit separation, etc. There are some standards and guidelines for what constitutes a good issue or PR, but these aren't written down anywhere.

To help contributors create higher-quality contributions (and thus reduce the review load), we should write contribution guidelines. If we put these in a file called CONTRIBUTING.md in the repo root, a link to these guidelines will be automatically shown whenever someone opens up a pullrequest or issue.

Things I think should appear in these guidelines:

• Contribution process involving github issues, pull requests and the mailing list.
• Issues are not for support and help with sketches.
• Commits should be logically separate and self-contained.
• Commit message guidelines (this comment is probably a good start).
• Rebasing PR's is ok and encouraged.
• Big changes, or changes to the API, or changes with backward compatibility trade-offs are best discussed on the mailing list first.

More?

[per1234]

Some suggestions:

• Contributing to the documentation. Should contributions be submitted to this repository or to the reference repository? The issues I see with using the reference repository for contributions are:
  • The content of the website language reference and the language reference included with the IDE are not in sync with the repository content.
  • It only contains the language reference and not other documentation present on arduino.cc. Maybe it would be better to put all the documentation in a repository and submit documentation contributions there and use this repository to submit contributions for the IDE only. It would be easier to avoid duplicated effort if there was only one recommended location for contributions to the documentation.
• Contributing to the official Arduino libraries. Should the contributions be made to this repository or to the specific library repository under the arduino-libraries account? https://www.arduino.cc/en/Reference/Libraries says:

Corrections, suggestions, and new documentation should be posted to the Forum.

[per1234]

Some of the information needed could be linked to or copied from the wiki pages:
https://github.com/arduino/Arduino/wiki/Development-Policy
https://github.com/arduino/Arduino/wiki/Git-Guide-for-Arduino EDIT: apparently this page has since been deleted.

[per1234]

Another thing that would be good to clarify is where arduino.cc website issues should be reported. Should they be submitted here, in the Website and Forum section of the Arduino forum, or emailed to the webmaster? https://www.arduino.cc/en/Main/ContactUs says to report website issues via email but I see many website issues successfully resolved in the Arduino IDE GitHub repository issue tracker. I recently had mastrolinux request that I submit an issue to the forum instead of here. It would be nice to have a single location for reporting website issues and I think a real issue tracker is the best option. If the IDE tracker is not the appropriate location then maybe a separate repository could be created as was done for forum-issues. A website specific repository could contain the website source to enable pull requests.

Consider adding a link to the forum-issues repository for people wanting to report Arduino forum issues.

[carlosperate]

I would like to emphasise that a single place that clearly states where to report issues in all aspects Arduino would be great, as right now things are all over the place and it is quite hard to tell what belongs where. I personally quite like the github tracker, and I've seen websites using an empty repository just to use it as a general issue tracker.

[per1234]

I'm willing to write a first draft of this if I can get some official answers to my questions. The Arduino community is a resource that could be more effectively utilized with a little guidance and infrastructure.