diff --git a/docs/contributor-guide/assets/checks-tab.png b/docs/contributor-guide/assets/checks-tab.png new file mode 100644 index 00000000..ee185495 Binary files /dev/null and b/docs/contributor-guide/assets/checks-tab.png differ diff --git a/docs/contributor-guide/assets/tester-build-artifacts.png b/docs/contributor-guide/assets/tester-build-artifacts.png new file mode 100644 index 00000000..ab9dada8 Binary files /dev/null and b/docs/contributor-guide/assets/tester-build-artifacts.png differ diff --git a/docs/contributor-guide/assets/tester-build-link.png b/docs/contributor-guide/assets/tester-build-link.png new file mode 100644 index 00000000..136a4794 Binary files /dev/null and b/docs/contributor-guide/assets/tester-build-link.png differ diff --git a/docs/contributor-guide/beta-testing.md b/docs/contributor-guide/beta-testing.md new file mode 100644 index 00000000..9f4dba11 --- /dev/null +++ b/docs/contributor-guide/beta-testing.md @@ -0,0 +1,106 @@ + + +# Beta Testing Guide + +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. + +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. + +--- + +❗ Make sure to always download the newest available tester build in order to ensure effective results from your beta testing efforts. + +--- + +Beta testing is done during both the proposal (pull request) and pre-release (nightly build) phases of development: + +## Testing Pull Requests + +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. + +The builds are updated if the author pushes changes to the PR. + +### Installation + +The tester build for a PR can be downloaded by following these instructions: + +1. Sign in to your [**GitHub**](https://github.com/) account.
+ (GitHub only allows downloads of the tester builds when you are signed in.) +1. Open the PR you are interested in.
+ They are listed here:
+ https://github.com/arduino/arduino-ide/pulls +1. Click the "**Checks**" tab at the top of the PR's page. +1. From the list on the left side of the page, click on "**Arduino IDE**". +1. Scroll down to the "**Artifacts**" section of the page that opens. +1. Click the download link for your operating system.
+ **ⓘ** For example, if you are using Windows, click the "**Windows_X86-64_zip**" link. +1. Wait for the download to finish. +1. Extract or install the downloaded file as usual. + +![checks tab](assets/checks-tab.png) + +![tester build link](assets/tester-build-link.png) + +![tester build artifacts](assets/tester-build-artifacts.png) + +#### Notes for macOS + +Beginning in macOS 10.14.5, the software [must be notarized to run](https://developer.apple.com/documentation/xcode/notarizing_macos_software_before_distribution). + +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. + +Due to this limitation, Mac users have two options for testing PRs from forks: + +##### The Safe Approach + +Build the version of the Arduino IDE you want to test from source instead of using the automatically created tester build. + +[Instructions for building the project](../development.md#build-from-source) + +##### The Risky Approach + +--- + +⚠ Please note that this approach is risky as you are lowering the security on your system, therefore we strongly discourage you from following it. + +--- + +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!). +1. Beta test the tester build. +1. Re-enable Gatekeeper after tests are done, following the guide linked above. + +### Feedback + +Feedback after beta testing a pull request is always valuable, regardless of which categories your findings fall under: + +- working as expected +- problems encountered +- areas for improvement + +Please submit feedback related to the changes made in the pull request as a PR review: + +https://docs.github.com/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews + +--- + +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. + +[More information on issue reports](issues.md#issue-report-guide) + +## Testing Nightly Build + +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. + +### Installation + +1. Open Arduino's "**Software**" page:
+ https://www.arduino.cc/en/software#nightly-builds +1. Select the appropriate download link from the "**Nightly Builds**" section of the page. +1. Wait for the download to finish. +1. Extract or install the downloaded file as usual. + +### Feedback + +If you discover any problems or areas for improvement please submit an issue report. + +[More information on issue reports](issues.md#issue-report-guide) diff --git a/docs/development.md b/docs/development.md index 2edfd0e5..ac8a2e5e 100644 --- a/docs/development.md +++ b/docs/development.md @@ -39,6 +39,12 @@ The _frontend_ is running as an Electron renderer process and can invoke service ## Build from source +--- + +**ⓘ** 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). + +--- + If you’re familiar with TypeScript, the [Theia IDE](https://theia-ide.org/), and if you want to contribute to the project, you should be able to build the Arduino IDE locally. 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 git push origin 1.2.3 ``` -## Notes for macOS contributors -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. -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. -Due to this limitation, Mac users have two options for testing contributions from forks: - -### The Safe approach (recommended) - -Follow [the instructions above](#build-from-source) to create the build environment locally, then build the code you want to test. - -### The Risky approach - -*Please note that this approach is risky as you are lowering the security on your system, therefore we strongly discourage you from following it.* -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!). -1. Download the unsigned artifact provided by the CI workflow run related to the Pull Request at each push. -1. Re-enable Gatekeeper after tests are done, following the guide linked above. - ## FAQ * *Can I manually change the version of the [`arduino-cli`](https://github.com/arduino/arduino-cli/) used by the IDE?*