The issue forms are configured to request the contributor to test using the nightly build of Arduino IDE before
submitting an issue in order to make sure the bug or feature request has not already been resolved.
Some time ago, the repository's readme contained a table of download links. The links in the issue forms pointed there.
That table was replaced with a link to the official "Software" page in order to reduce unnecessary verbosity and
maintenance burden of the project's documentation content.
The issue form links were not updated at that time. The resulting additional link in the chain made obtaining the
nightly build less convenient for the contributor to obtain.
The links are hereby updated to point directly to the list of nightly build download links on the arduino.cc "Software"
page.
Contributor are presented with an issue template chooser page at the start of the issue creation process.
In addition to the issue report templates, some "contact links" provide information and links to other communication
channels. In order to encourage high quality issues, a link to the "issue report guide" is included on this page.
Previously that link pointed to an incorrect URL, resulting in a 404 error for those who visited it. The URL is hereby
corrected.
Documentation of how to contribute to the project gives everyone the opportunity to participate, while also reducing the
maintenance effort and increasing the quality of contributions.
This guide documents the various ways of contributing to the project.
GitHub issue forms are used in this repository to facilitate the creation of high quality issues. These provide input
fields for each of the distinct classes of information which will be essential for the evaluation of the issues.
One of these fields is for the user's operating system. A dropdown menu is used for the selection of the high level
operating system type. Previously this only permitted the selection of a single option. A devoted contributor might have
made the effort to determine that the issue applies to multiple operating system types only to be met with the inability
to provide this information via the dedicated field.
The field also did not offer an option to indicate that the operating system was irrelevant to the issue (e.g., a
subject related to the repository assets).
Those issues are resolved by the following changes:
- Configure the field to allow multiple selections
- Add a "N/A" option to the menu
This project provides the contributors with templates for the fundamental categories of issues:
- bug report
- feature request
This is helpful to the maintainers and developers because it establishes a standardized framework for the issues and
encourages the contributors to provide the essential information.
GitHub's original issue template system is very crude, simply pre-populating the issue description field with the text
from the template file.
https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#creating-issue-templates
The contributor may be confused by being presented with a mass of Markdown and placeholder
content where they expected a field to write their issue. They also may find it inconvenient to manuever around the
framework content and replace the placeholder content.
A far better system is now available with GitHub's recently introduced form-based issue templates:
https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#creating-issue-forms
The user is now presented with a web form. These may include multi-line input fields that have the same formatting and
attachment capabilities as the standard GitHub Issue composer, but also additional elements such as menus and checkboxes.
The use of this form-based system should provide a much better experience for the contributors and also result in higher
quality issues.
The automatically created issue template chooser provides a menu of links to the available issue report templates as
well as the security policy at the start of the issue creation process.
It is also possible to add additional arbitrary items to the chooser, through GitHub's "Contact Links" feature. These
are defined in a configuration file:
https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#configuring-the-template-chooser
These links offer the possibility to redirect support requests and other sub-optimal usages of the issues to the
appropriate location. This benefits the user by providing them with a fast and frictionless path to what they need, and
benefits the maintainers by preventing inappropriate issues.
On every push that changes relevant files, and periodically, configure the repository's issue and pull request labels
according to the universal, shared, and local label configuration files.
This repositories label names have been customized. The label names defined in the templates will automatically be added
to issues created using that template, so the template labels must match with the repository's labeling convention.
The bug report template provides some example values for OS and version. The previous examples were completely
irrelevant to this project due to using an unsupported OS and a different versioning scheme. This might cause confusion,
or at least seem odd, to the contributor.
At the first step of creating an issue, a menu of issue types will be presented:
- Bug report
- Feature request
- Report a security vulnerability
If one of the first two are selected, the issue body field will be pre-filled with the template Markdown.
"Report a security vulnerability" will take them to Arduino's global security disclosure policy, which provides further guidance.
If none of the categories in the issue type chooser are applicable, the "Open a blank issue." link at the bottom of the
page can be selected, which will provide the non-templated issue creation experience.
These templates are copies of https://github.com/arduino/arduino-pro-ide/tree/master/.github/ISSUE_TEMPLATE
