Add contributor guide templates #270
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Arduino tooling projects are produced through the collaboration of numerous contributors. High quality documentation of how to contribute to the projects can give everyone the opportunity to participate, while also reducing maintenance effort and increasing quality of contributions. Producing such documentation for each project can seem a daunting task. Those who are knowledgeable enough to do so are also the ones less likely to recognize the need for it. These factors have resulted in less than ideal coverage of contribution documentation in the Arduino Tooling projects. A collection of "template" contribution guides are established here. These are intended to be easily applied to Arduino tooling projects, reducing the effort to establish and maintain contribution documentation. This guides document the various ways of contributing to the project. It takes advantage of GitHub's "contributing guidelines" feature to increase the visibility of the information to prospective contributors. The promoted "CONTRIBUTING.md" file is used as an entry point to the guide, with links from there leading to dedicated guides for each specific type of contribution. In this way, the contributor is only presented with relevant information, improving the approachability and readability of the content.
Documentation of how to contribute to the project gives everyone the opportunity to participate, while also reducing maintenance effort and increasing quality of contributions. This guide documents the various ways of contributing to the project. It takes advantage of GitHub's "contributing guidelines" feature to increase the visibility of the information to prospective contributors. The promoted "CONTRIBUTING.md" file is used as an entry point to the guide, with links from there leading to dedicated guides for each specific type of contribution. In this way, the contributor is only presented with relevant information, improving the approachability and readability of the content.
per1234
added
topic: documentation
MatteoPologruto
approved these changes
Sep 15, 2022
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Arduino tooling projects are produced through the collaboration of numerous contributors.
High quality documentation of how to contribute to the projects can give everyone the opportunity to participate, while also reducing maintenance effort and increasing quality of contributions.
Producing such documentation for each project can seem a daunting task. Those who are knowledgeable enough to do so are also the ones less likely to recognize the need for it. These factors have resulted in less than ideal coverage of contribution documentation in the Arduino Tooling projects.
A collection of "template" contribution guides are established here. These are intended to be easily applied to Arduino tooling projects, reducing the effort to establish and maintain contribution documentation.
The guides document the various ways of contributing to the project.
It takes advantage of GitHub's "contributing guidelines" feature to increase the visibility of the information to prospective contributors. The promoted
CONTRIBUTING.mdfile is used as an entry point to the guide, with links from there leading to dedicated guides for each specific type of contribution. In this way, the contributor is only presented with relevant information, improving the approachability and readability of the content.In order to give the template an trial run, and to obtain review of it in the context of a real world usage, I applied it to the
arduino/arduino-iderepository: arduino/arduino-ide#1419That repository deviates fairly significantly from the standardized Arduino tooling project structure, so more modifications were required than would typically be the case in an application. Even so, it think it serves as demonstration of the contributor guide in action:
https://github.com/arduino/arduino-ide/blob/main/docs/CONTRIBUTING.md
In addition, I apply the template to this repository via this PR:
https://github.com/per1234/tooling-project-assets/blob/contributor-guide/docs/CONTRIBUTING.md