Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Define guidelines for contributing #3368

Closed
matthijskooijman opened this issue Jun 19, 2015 · 5 comments
Closed

Define guidelines for contributing #3368

matthijskooijman opened this issue Jun 19, 2015 · 5 comments
Labels
Component: Documentation Related to Arduino's documentation content

Comments

@matthijskooijman
Copy link
Collaborator

matthijskooijman commented Jun 19, 2015

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
Copy link
Collaborator

per1234 commented Jun 20, 2015

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
Copy link
Collaborator

per1234 commented Jun 30, 2015

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.

@ffissore ffissore self-assigned this Jul 1, 2015
@per1234
Copy link
Collaborator

per1234 commented Jul 17, 2015

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
Copy link
Contributor

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
Copy link
Collaborator

per1234 commented Oct 20, 2015

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Component: Documentation Related to Arduino's documentation content
Projects
None yet
Development

No branches or pull requests

5 participants