Go Down

Topic: Contributing (Read 436 times) previous topic - next topic

TomasRoj

What is the best thing to do when you want to contribute to arduiino community? I mean writing code, editing docs etc.

pert

The answer really depends on your level and area of expertise. A C++ programmer could make very valuable contributions to the libraries. A Java programmer, to the Arduino IDE code. A Go programmer, to the arduino-builder and arduino-cli tools. A electrical engineer to documentation/tutorials of circuits.



One place where anyone with a desire to contribute can get involved is by beta testing the Arduino IDE or arduino-cli and submitting high quality issue reports for any unique bugs you discover. There are currently two different versions of the Arduino IDE you can use for beta testing:


arduino-cli is a tool that allows you to run the same actions as with the Arduino IDE's GUI from the command line, using a lightweight tool. This tool is currently in alpha stage and is under active development so there is a real opportunity for the community to get involved in making sure this will turn out to be an excellent tool. You can download the latest release from this page, which provides a build for each OS:
https://github.com/arduino/arduino-cli/releases
For beta testing, you may also want to build the latest development version of arduino-cli from the tip of the master branch. Go makes it actually surprisingly easy to do this.



There's a tricky thing with contributing to open source projects. Some might think "volunteers mean free labor so it's always a win". The truth is that most any action a volunteer takes is going to require some corresponding effort on the part of someone else to review and act on it. It's quite possible for this equation to sum to a volunteer contribution having an overall negative effect, even if done with the best of intentions.

We must make a real effort to ensure that our contributions will have a positive overall effect. Otherwise, what's the point? Let's take the example of reporting a bug you found while beta testing.

The first thing you need to do is make sure the bug hasn't already been fixed. The hourly build of the Arduino IDE is updated automatically within one hour of a new commit being made to the Arduino IDE's repository. So if you are using an outdated version of the hourly or beta build, you might have found a bug that has been fixed since that time. So you always need to make sure you're using the current version of the hourly/beta build.

The next thing you need to do is determine the proper place to report the bug. Arduino has many repositories. There is a guide to the appropriate location for each type of issue here:
https://github.com/arduino/Arduino/blob/4c9da50e57030aebd4320fcc24e3f497f504b663/CONTRIBUTING.md#issues

Now you need to make sure that nobody else has already reported the bug or submitted a pull request to fix it. Duplicate bug reports are not helpful. The GitHub issue trackers have a nice search feature you can use to search for previous bug reports on the topic. The tricky thing is that the search field comes prefilled with "is:issue is:open", which restricts the search to issues that are open. But we don't want to search only open issues. It's also important to search the pull requests and closed issues. So you need to delete the "is:issue is:open" from the search field before entering your keywords.

Now that you have verified that you have found a valid, unique bug, it's time to write your issue report. Start by stating the version of the software you're using (shown on the title bar or the About page in the case of the Arduino IDE) and your operating system. Next, a clear description of the issue. It's very important to provide enough information so that anyone can easily reproduce the issue. I like to provide a precise and complete set of steps to follow, which don't make any assumptions the person following them has special knowledge. Once you're done writing it, read it over while pretending that you're someone else who doesn't know anything about the issue. Is everything clear? An issue report that makes the bug very obvious will have much more likelihood of getting resolved quickly and efficiently. The vague ones that are missing information tend to get ignored and are quickly buried under the many other incoming issues.

The final step is to be responsive to any further requests for information. Make sure you have your GitHub account set so that you will receive notifications. There are lots of issue reports that are stalled because the person who reported it never responded to a request for info. These will usually just end up getting closed after some time passes.

There is a guide to contributing to Arduino's repositories (which also provides useful information about contributing to open source projects in general) here:
https://github.com/arduino/Arduino/blob/4c9da50e57030aebd4320fcc24e3f497f504b663/CONTRIBUTING.md




Another option for contributing that most anyone can help with is documentation. Arduino has a lot of documentation and there is certainly room for improvement. Someone who is early in their journey with learning Arduino can actually have an advantage in contributing to documentation. The reason is that very experienced people tend to forget how to communicate technical information to beginners. For someone like me who has recent memories of being a beginner, it's easier for me to see where the documentation would not make sense for someone who doesn't already have familiarity with the subject matter.

The easiest part of the documentation to contribute to is the Arduino Language Reference:
http://www.arduino.cc/reference/en
There is a tutorial for contributing to it here:
https://create.arduino.cc/projecthub/Arduino_Genuino/contribute-to-the-arduino-reference-af7c37

Unfortunately, there is not quite such an efficient system in place for the rest of the Arduino documentation content, but contributions are still very welcome. If you find an error or want to suggest an improvement to the non-language reference content, you only need to submit an issue report to the appropriate repository. If the documentation is for a specific library, you should submit it to that library's repository. Otherwise, you can submit it to the arduino/Arduino repository, which acts as a "catch-all" for issue reports in addition to hosting the Arduino IDE code:
https://github.com/arduino/Arduino/issues

Another opportunity to contribute for people with fluency in languages other than English is to translate content. There are versions of the Arduino Language Reference for the following languages:

If you would like to add a translation for a language not on the list above, and are willing to take an active role in the translation work, Arduino will be happy to consider creating a new repository for that project. You could open an issue report with a proposal for new language translations in the arduino/reference-en repository.

You can also contribute to the translation of the Arduino IDE's text to 83 different languages via Transifex:
https://www.transifex.com/mbanzi/arduino-ide-15/

Robin2

The answer really depends on ...
Full marks for an extremely useful overview of the contribution process for development of the Arduino system - even though I don't envisage making use of it myself.

...R
Two or three hours spent thinking and reading documentation solves most programming problems.

pert

Well, you already contribute plenty in your own way by helping out so many people here on the forum.

It's really wonderful how thousands of people from all over the world have each found their own ways of contributing to this project. Whether it's writing libraries, making YouTube videos, spreading the word on social media, volunteering at a hackerspace, etc., it all has accumulated into this incredible thing.

AWOL

The answer really depends on your level and area of expertise. A C++ programmer could make very valuable contributions to the libraries. A Java programmer, to the Arduino IDE code. A Go programmer, to the arduino-builder and arduino-cli tools. A electrical engineer to documentation/tutorials of circuits.
...and if you don't tick any of those boxes, apply to be a moderator

Go Up