Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 2682027

Browse files
committed
Add contributor guide templates
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.
1 parent 2d7735e commit 2682027

File tree

21 files changed

+635
-7
lines changed

21 files changed

+635
-7
lines changed

‎.markdown-link-check.json‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,19 @@
1212
"aliveStatusCodes": [200, 206],
1313
"ignorePatterns": [
1414
{
15-
"pattern": "^CONTRIBUTING\\.md#building-the-source-code$"
15+
"pattern": "^../development\\.md#development-guide$"
16+
},
17+
{
18+
"pattern": "^contributor-guide/beta-testing\\.md#beta-testing-guide$"
19+
},
20+
{
21+
"pattern": "^development\\.md#building-the-project$"
22+
},
23+
{
24+
"pattern": "^development\\.md#development-guide$"
25+
},
26+
{
27+
"pattern": "^issues\\.md#issue-report-guide$"
1628
},
1729
{
1830
"pattern": "/TODO_REPO_NAME/"

‎documentation-templates/README.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Documentation Templates
2+
3+
## Contributor Guide
4+
5+
The file `CONTRIBUTING.md` serves as an entry point to the content. This file is given special treatment by GitHub, which presents it to potential contributors:
6+
7+
https://docs.github.com/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors
8+
9+
### Installation
10+
11+
Install the files and folders from [`contributor-guide/general/`](contributor-guide/general/) to the `docs/` subfolder of the repository.
12+
13+
#### Beta Testing Guide
14+
15+
An additional file named `beta-testing.md` must be added to the `docs/contributor-guide/` subfolder of the repository.
16+
17+
##### Application Projects
18+
19+
If tester builds are generated for the project, use the template files from [`contributor-guide/application/contributor-guide/beta-testing.md`](contributor-guide/application/contributor-guide/beta-testing.md).
20+
21+
The project is assumed to use a workflow with the standardized name "**Publish Tester Build**" to produce tester builds for pull requests.
22+
23+
A workflow template for Go-based projects is available [here](../workflow-templates/publish-go-tester-task.md).
24+
25+
##### Other Projects
26+
27+
A basic template providing the standardized structure for the document is available at [`contributor-guide/other/contributor-guide/beta-testing.md`](contributor-guide/other/contributor-guide/beta-testing.md).
28+
29+
#### Development Guide
30+
31+
An additional file named `development.md` must be added to the `docs/` subfolder of the repository.
32+
33+
##### Task-Based Projects
34+
35+
For projects which use the standardized Task-based approach to project management, use the template file from [`contributor-guide/task/development.md`](contributor-guide/task/development.md).
36+
37+
The taskfile must contain the following standardized "umbrella" tasks:
38+
39+
- `build` - build the project
40+
- `check` - run all tasks that check for problems with the project
41+
- `fix` - run all tasks that make automated corrections to the project's files
42+
43+
##### Other Projects
44+
45+
A basic template providing the standardized structure for the document is available at [`contributor-guide/other/development.md`](contributor-guide/other/development.md).
46+
47+
#### Configuration
48+
49+
"**TODO**" comments and placeholders mark the locations in the documents where project-specific adjustments or additions should be made.
50+
51+
### Commit message
52+
53+
```text
54+
Add a project contributor guide
55+
56+
Documentation of how to contribute to the project gives everyone the opportunity to participate, while also reducing
57+
maintenance effort and increasing quality of contributions.
58+
59+
This guide documents the various ways of contributing to the project.
60+
61+
It takes advantage of GitHub's "contributing guidelines" feature to increase the visibility of the information to
62+
prospective contributors. The promoted "CONTRIBUTING.md" file is used as an entry point to the guide, with links from
63+
there leading to dedicated guides for each specific type of contribution. In this way, the contributor is only presented
64+
with relevant information, improving the approachability and readability of the content.
65+
```
66+
67+
### PR message
68+
69+
```markdown
70+
Documentation of how to contribute to the project gives everyone the opportunity to participate, while also reducing maintenance effort and increasing quality of contributions.
71+
72+
This guide documents the various ways of contributing to the project.
73+
74+
It takes advantage of [GitHub's "contributing guidelines" feature](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors) 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.
75+
```
52.4 KB
Loading[フレーム]
65.9 KB
Loading[フレーム]
26.4 KB
Loading[フレーム]
Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
<!-- Source: https://github.com/arduino/tooling-project-assets/blob/main/documentation-templates/contributor-guide/application/contributor-guide/beta-testing.md -->
2+
3+
# Beta Testing Guide
4+
5+
Beta testing of development versions is a valuable contribution to the project. You can help to ensure the quality of the production release that will be distributed to the user community.
6+
7+
Builds of the project are automatically created after every relevant change to the project in order to make it easy for anyone to participate in the testing effort.
8+
9+
---
10+
11+
❗ Make sure to always download the newest available tester build in order to ensure effective results from your beta testing efforts.
12+
13+
---
14+
15+
Beta testing is done during both the proposal (pull request) and pre-release (nightly build) phases of development:
16+
17+
## Testing Pull Requests
18+
19+
Tester builds are automatically created for every [pull request](https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) (PR) that proposes a relevant change.
20+
21+
The builds are updated if the author pushes changes to the PR.
22+
23+
### Installation
24+
25+
The tester build for a PR can be downloaded by following these instructions:
26+
27+
1. Sign in to your [**GitHub**](https://github.com/) account.<br />
28+
(GitHub only allows downloads of the tester builds when you are signed in.)
29+
1. Open the PR you are interested in.<br />
30+
They are listed here:<br />
31+
https://github.com/arduino/TODO_REPO_NAME/pulls
32+
1. Click the "**Checks**" tab at the top of the PR's page.
33+
1. From the list on the left side of the page, click on "**Publish Tester Build**".
34+
1. From the "**Artifacts**" section of the page that opens, click the download link for your operating system.<br />
35+
**i** For example, if you are using Windows, click the "**Windows_X86-64_zip**" link.
36+
1. Wait for the download to finish.
37+
1. Extract or install the downloaded file as usual.
38+
39+
![checks tab](assets/checks-tab.png)
40+
41+
![tester build link](assets/tester-build-link.png)
42+
43+
![tester build artifacts](assets/tester-build-artifacts.png)
44+
45+
### Feedback
46+
47+
Feedback after beta testing a pull request is always valuable, regardless of which categories your findings fall under:
48+
49+
- working as expected
50+
- problems encountered
51+
- areas for improvement
52+
53+
Please submit feedback related to the changes made in the pull request as a PR review:
54+
55+
https://docs.github.com/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews
56+
57+
---
58+
59+
If you discover problems or areas for improvement that are unrelated to the changes made by the PR (i.e., they also occur when using the [nightly build](#testing-nightly-build)), please submit that feedback as an issue report instead of a review.
60+
61+
[More information on issue reports](issues.md#issue-report-guide)
62+
63+
## Testing Nightly Build
64+
65+
Builds of the project's production branch are produced daily. This build represents the current pre-release state of the project, which is planned for distribution in the next release.
66+
67+
### Installation
68+
69+
<!-- TODO: Add instructions for installation of project's nightly build -->
70+
71+
### Feedback
72+
73+
If you discover any problems or areas for improvement please submit an issue report.
74+
75+
[More information on issue reports](issues.md#issue-report-guide)
Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
<!-- Source: https://github.com/arduino/tooling-project-assets/blob/main/documentation-templates/contributor-guide/general/CONTRIBUTING.md -->
2+
3+
# Contributor Guide
4+
5+
Thanks for your interest in contributing to this project!
6+
7+
There are several ways you can get involved:
8+
9+
| Type of contribution | Contribution method |
10+
| ----------------------------------------- | -------------------------------------------------------------------------------- |
11+
| - Support<br/>- Question<br/>- Discussion | Post on the [**Arduino Forum**][forum] |
12+
| - Bug report<br/>- Feature request | Issue report (see the guide [**here**][issues]) |
13+
| Testing | Beta testing, PR review (see the guide [**here**][beta-testing]) |
14+
| - Bug fix<br/>- Enhancement | Pull request (see the guide [**here**][prs]) |
15+
| Monetary | - [Donate][donate]<br/>- [Sponsor][sponsor]<br/>- [Buy official products][store] |
16+
17+
[forum]: https://forum.arduino.cc
18+
[issues]: contributor-guide/issues.md#issue-report-guide
19+
[beta-testing]: contributor-guide/beta-testing.md#beta-testing-guide
20+
[prs]: contributor-guide/pull-requests.md#pull-request-guide
21+
[donate]: https://www.arduino.cc/en/donate/
22+
[sponsor]: https://github.com/sponsors/arduino
23+
[store]: https://store.arduino.cc
24+
25+
## Resources
26+
27+
- [**Development Guide**](development.md#development-guide)
39.1 KB
Loading[フレーム]
Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
<!-- Source: https://github.com/arduino/tooling-project-assets/blob/main/documentation-templates/contributor-guide/general/contributor-guide/issues.md -->
2+
3+
# Issue Report Guide
4+
5+
---
6+
7+
❗ Do you need help or have a question about using this project? Support requests should be made to the [Arduino Forum](https://forum.arduino.cc).
8+
9+
---
10+
11+
High quality bug reports and feature requests are valuable contributions to this project. These can be made by submitting an issue report to the project's GitHub repository:
12+
13+
https://github.com/arduino/TODO_REPO_NAME/issues/new/choose
14+
15+
## Before Reporting an Issue
16+
17+
- Give the latest development version a test drive to see if your issue was already resolved:<br />
18+
<!-- TODO: Nightly build link -->
19+
- Search [existing pull requests and issues](https://github.com/arduino/TODO_REPO_NAME/issues?q=) to see if it was already reported.<br />
20+
If you have additional information to provide about an existing issue, please comment there instead of creating a duplicate. You can use [GitHub's "Reactions" feature](https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/) if you only want to express support 👍.
21+
22+
## Qualities of an Excellent Report
23+
24+
- Concise and descriptive issue title.<br />
25+
Vague titles make it difficult to decipher the purpose of the issue when looking through the list of reports, which might result in your issue not being given proper attention.
26+
- Describe the issue and what behavior you were expecting.<br />
27+
Include the full and exact text of any relevant error or warning messages you might have encountered.
28+
- Provide a full set of steps necessary to reproduce the issue.<br />
29+
Demonstration code or commands should be complete and simplified to the minimum necessary to reproduce the issue.
30+
- Be responsive.<br />
31+
We may need you to provide additional information in order to investigate and resolve the issue.<br />
32+
Make sure your GitHub account is configured so that you will receive notifications of responses to your issue report.
33+
- If you find a solution to your problem, please comment on your issue report with an explanation of how you were able to fix it, then close the issue.

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /