Skip to content

Commit 0ba88d5

Browse files
committed
Move beta testing information to a dedicated documentation file
Previously, the information about tester builds was mixed in with the documentation about building the project from source. The two subjects are of relevance to two distinct contribution options. Building from source will primarily be done by developers working on the project code base. Tester builds will be used by beta testers and reviewers. For this reason, it doesn't make sense to require beta testers to wade through a lot of development documentation not directly related to their work in order to find the instructions for obtaining tester builds. Likewise, it doesn't make sense to clutter up the development documentation with such information. Moving the information about tester builds to a dedicated file makes it easier for the interested parties to find, and also allows the creation of a comprehensive guide for beta testers without making a negative impact on the development documentation content.
1 parent 96e229d commit 0ba88d5

File tree

5 files changed

+112
-16
lines changed

5 files changed

+112
-16
lines changed
41.7 KB
Loading
Loading
Loading
+106
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
<!-- Source: https://github.com/arduino/tooling-project-assets/blob/main/documentation-templates/contributor-guide/application/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/arduino-ide/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 "**Arduino IDE**".
34+
1. Scroll down to the "**Artifacts**" section of the page that opens.
35+
1. Click the download link for your operating system.<br />
36+
**** For example, if you are using Windows, click the "**Windows_X86-64_zip**" link.
37+
1. Wait for the download to finish.
38+
1. Extract or install the downloaded file as usual.
39+
40+
![checks tab](assets/checks-tab.png)
41+
42+
![tester build link](assets/tester-build-link.png)
43+
44+
![tester build artifacts](assets/tester-build-artifacts.png)
45+
46+
#### Notes for macOS
47+
48+
Beginning in macOS 10.14.5, the software [must be notarized to run](https://developer.apple.com/documentation/xcode/notarizing_macos_software_before_distribution).
49+
50+
For security reasons, signing and notarization are disabled when creating tester builds for pull requests from forks of this repository. This means that macOS will block you from running the tester builds for those PRs.
51+
52+
Due to this limitation, Mac users have two options for testing PRs from forks:
53+
54+
##### The Safe Approach
55+
56+
Build the version of the Arduino IDE you want to test from source instead of using the automatically created tester build.
57+
58+
[Instructions for building the project](../development.md#build-from-source)
59+
60+
##### The Risky Approach
61+
62+
---
63+
64+
⚠ Please note that this approach is risky as you are lowering the security on your system, therefore we strongly discourage you from following it.
65+
66+
---
67+
68+
1. Use [this guide](https://help.apple.com/xcode/mac/10.2/index.html?localePath=en.lproj#/dev9b7736b0e), in order to disable Gatekeeper (at your own risk!).
69+
1. Beta test the tester build.
70+
1. Re-enable Gatekeeper after tests are done, following the guide linked above.
71+
72+
### Feedback
73+
74+
Feedback after beta testing a pull request is always valuable, regardless of which categories your findings fall under:
75+
76+
- working as expected
77+
- problems encountered
78+
- areas for improvement
79+
80+
Please submit feedback related to the changes made in the pull request as a PR review:
81+
82+
https://docs.github.com/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews
83+
84+
---
85+
86+
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.
87+
88+
[More information on issue reports](issues.md#issue-report-guide)
89+
90+
## Testing Nightly Build
91+
92+
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.
93+
94+
### Installation
95+
96+
1. Open Arduino's "**Software**" page:<br />
97+
https://www.arduino.cc/en/software#nightly-builds
98+
1. Select the appropriate download link from the "**Nightly Builds**" section of the page.
99+
1. Wait for the download to finish.
100+
1. Extract or install the downloaded file as usual.
101+
102+
### Feedback
103+
104+
If you discover any problems or areas for improvement please submit an issue report.
105+
106+
[More information on issue reports](issues.md#issue-report-guide)

docs/development.md

+6-16
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,12 @@ The _frontend_ is running as an Electron renderer process and can invoke service
3939

4040
## Build from source
4141

42+
---
43+
44+
**** If you only want to test an existing version of the project, automatically generated builds are available for download without building from source. See the instructions in the [**beta testing guide**](contributor-guide/beta-testing.md#beta-testing-guide).
45+
46+
---
47+
4248
If you’re familiar with TypeScript, the [Theia IDE](https://theia-ide.org/), and if you want to contribute to the
4349
project, you should be able to build the Arduino IDE locally.
4450
Please refer to the [Theia IDE prerequisites](https://github.com/eclipse-theia/theia/blob/master/doc/Developing.md#prerequisites) documentation for the setup instructions.
@@ -89,22 +95,6 @@ This project is built on [GitHub Actions](https://github.com/arduino/arduino-ide
8995
git push origin 1.2.3
9096
```
9197

92-
## Notes for macOS contributors
93-
Beginning in macOS 10.14.5, the software [must be notarized to run](https://developer.apple.com/documentation/xcode/notarizing_macos_software_before_distribution). The signing and notarization processes for the Arduino IDE are managed by our Continuous Integration (CI) workflows, implemented with GitHub Actions. On every push and pull request, the Arduino IDE is built and saved to a workflow artifact. These artifacts can be used by contributors and beta testers who don't want to set up a build system locally.
94-
For security reasons, signing and notarization are disabled for workflow runs for pull requests from forks of this repository. This means that macOS will block you from running those artifacts.
95-
Due to this limitation, Mac users have two options for testing contributions from forks:
96-
97-
### The Safe approach (recommended)
98-
99-
Follow [the instructions above](#build-from-source) to create the build environment locally, then build the code you want to test.
100-
101-
### The Risky approach
102-
103-
*Please note that this approach is risky as you are lowering the security on your system, therefore we strongly discourage you from following it.*
104-
1. Use [this guide](https://help.apple.com/xcode/mac/10.2/index.html?localePath=en.lproj#/dev9b7736b0e), in order to disable Gatekeeper (at your own risk!).
105-
1. Download the unsigned artifact provided by the CI workflow run related to the Pull Request at each push.
106-
1. Re-enable Gatekeeper after tests are done, following the guide linked above.
107-
10898
## FAQ
10999

110100
* *Can I manually change the version of the [`arduino-cli`](https://github.com/arduino/arduino-cli/) used by the IDE?*

0 commit comments

Comments
 (0)