Merge pull request #119 from bcmi-labs/doc-ci-cd

Updated the documentation.

.github/workflows/build.yml

@@ -5,7 +5,7 @@ on:
     branches:
       - master
     tags:
-      - 'v[0-9]+.[0-9]+.[0-9]+*'
+      - '[0-9]+.[0-9]+.[0-9]+*'
   pull_request:
     branches:
       - master

README.md

@@ -1,50 +1,86 @@
 # Arduino Pro IDE
 
-[![Build Status](https://dev.azure.com/typefox/Arduino/_apis/build/status/bcmi-labs.arduino-editor?branchName=master)](https://dev.azure.com/typefox/Arduino/_build/latest?definitionId=4&branchName=master)
+![Arduino Pro IDE](https://github.com/bcmi-labs/arduino-editor/workflows/Arduino%20Pro%20IDE/badge.svg)
 
-> **Beware:** This is very much work-in-progress. Things can and probably will be broken, even on master.
+### Download
 
-This repo contains a proof-of-concept for an Arduino IDE based on Theia.
+You can download the latest version of the Arduino Pro IDE application for the supported platforms from the [GitHub release page](https://github.com/arduino/arduino-pro-ide/releases) or following the links in the following table.
-It's built on top of a [fork of the arduino-cli](https://github.com/typefox/arduino-cli/tree/daemon) that sports a gRPC interface.
 
-## How to try (offline)
+#### Latest version
 
-### Prerequisites
+Platform  | 32 bit                   | 64 bit                   |
-You should be able to build Theia locally. The requirements are defined [here](https://github.com/theia-ide/theia/blob/master/doc/Developing.md#prerequisites).
+--------- | ------------------------ | ------------------------ |
+Linux     |                          | [Linux 64 bit]           |
+Linux ARM | [🚧 Work in progress...] | [🚧 Work in progress...] |
+Windows   |                          | [Windows 64 bit]         |
+macOS     |                          | [macOS 64 bit]           |
 
-```
+[🚧 Work in progress...]: https://github.com/arduino/arduino-pro-ide/issues/287
-git clone https://github.com/bcmi-labs/arduino-editor
+[Linux 64 bit]: https://downloads.arduino.cc/arduino-pro-ide/arduino-pro-ide_latest_Linux_64bit.zip
-cd arduino-editor
+[Windows 64 bit]: https://downloads.arduino.cc/arduino-pro-ide/arduino-pro-ide_latest_Windows_64bit.zip
+[macOS 64 bit]: https://downloads.arduino.cc/arduino-pro-ide/arduino-pro-ide_latest_macOS_64bit.dmg
+
+#### Previous versions
+
+These are available from the [GitHub releases page](https://github.com/arduino/arduino-pro-ide/releases).
+
+#### Nightly builds
+
+These builds are generated every day at 03:00 GMT from the `master` branch and
+should be considered unstable. In order to get the latest nightly build
+available for the supported platform, use the following links:
+
+Platform  | 32 bit                   | 64 bit                   |
+--------- | ------------------------ | ------------------------ |
+Linux     |                          | [Nightly Linux 64 bit]   |
+Linux ARM | [🚧 Work in progress...] | [🚧 Work in progress...] |
+Windows   |                          | [Nightly Windows 64 bit] |
+macOS     |                          | [Nightly macOS 64 bit]   |
+
+[🚧 Work in progress...]: https://github.com/arduino/arduino-pro-ide/issues/287
+[Nightly Linux 64 bit]: https://downloads.arduino.cc/arduino-pro-ide/nightly/arduino-pro-ide_nightly-latest_Linux_64bit.zip
+[Nightly Windows 64 bit]: https://downloads.arduino.cc/arduino-pro-ide/nightly/arduino-pro-ide_nightly-latest_Windows_64bit.zip
+[Nightly macOS 64 bit]: https://downloads.arduino.cc/arduino-pro-ide/nightly/arduino-pro-ide_nightly-latest_macOS_64bit.dmg
+
+> These links return an HTTP `302: Found` response, redirecting to latest
+  generated builds by replacing `latest` with the latest available build
+  date, using the format YYYYMMDD (i.e for 2019/Aug/06 `latest` is
+  replaced with `20190806` )
+
+### Build from source
+
+If you’re familiar with TypeScript, the [Theia IDE](https://theia-ide.org/), and of you want to contribute to the
+project, you should be able to build the Arduino Pro IDE locally. Please refer to the [Theia IDE prerequisites](https://github.com/theia-ide/theia/blob/master/doc/) documentation for the setup instructions.
+
+### Build
+```sh
 yarn
+```
+
+### Rebuild the native dependencies
+```sh
 yarn rebuild:electron
-yarn --cwd electron-app start
+```
+Note: this step takes long. It completes in 4-5 minutes on a MacBook Pro, 2.9 GHz Quad-Core Intel Core i7.
+
+### Start
+```sh
+yarn start
 ```
 
-If you want to switch back to the browser-based example, execute the following in the repository root
+### CI
+
+This project is built on [GitHub Actions](https://github.com/bcmi-labs/arduino-editor/actions?query=workflow%3A%22Arduino+Pro+IDE%22).
+
+ - _Snapshot_ builds run when changes are pushed to the `master` branch, or when a PR is created against the `master` branch. For the sake of the review and verification process, the build artifacts can be downloaded from the GitHub Actions page. Note: [due to a limitation](https://github.com/actions/upload-artifact/issues/80#issuecomment-630030144) with the GH Actions UI, you cannot download a particular build, but you have to get all together inside the `build-artifacts.zip`.
+ - _Nightly_ builds run every day at 03:00 GMT from the `master` branch.
+ - _Release_ builds run when a new tag is pushed to the remote. The tag must follow the [semver](https://semver.org/). For instance, `1.2.3` is a correct tag, but `v2.3.4` won't work. Steps to trigger a new release build:
+   - Create a local tag:
+    ```sh
+    git tag -a 1.2.3 -m "Creating a new tag for the `1.2.3` release."
     ```
-yarn rebuild:browser
+   - Push it to the remote:
-```
+   ```sh
-Then you can start the browser example again:
+    git push origin 1.2.3
-```
-yarn --cwd browser-app start
    ```
 
-Click [here](./arduino-ide-extension/README.md) for more details on various IDE services, and the Arduino Pro IDE implementation in general.
-
-
-## Arduino Pro IDE Electron Application
-The project is built on [Azure DevOps](https://dev.azure.com/typefox/Arduino).
-
-Currently, we provide the Arduino Pro IDE for the following platforms:
- - Windows,
- - macOS, and
- - Linux.
-   
-You can download the latest release applications fom [here](https://github.com/bcmi-labs/arduino-editor/releases/latest).
-If you want to get a nightly build, go to the [Azure DevOps page](https://dev.azure.com/typefox/Arduino/_build?definitionId=4),
-and follow the steps from below.
-
-<img width="500" src="static/download_01.gif">
-<img width="500" src="static/download_02.gif">
-
-Click [here](./electron/README.md) for more details on the CI/CD, the GitHub release, and the build process in general.

electron/build/template-package.json

@@ -79,7 +79,10 @@
       "hardenedRuntime": true,
       "gatekeeperAssess": false,
       "entitlements": "resources/entitlements.mac.plist",
-      "entitlementsInherit": "resources/entitlements.mac.plist"
+      "entitlementsInherit": "resources/entitlements.mac.plist",
+      "target": [
+        "dmg"
+      ]
     },
     "linux": {
       "target": [

electron/packager/config.js

@@ -79,8 +79,6 @@ function getVersion() {
         if (!semver.valid(version)) {
             throw new Error(`Invalid patched version: '${version}'.`);
         }
-    } else {
-        version = `v${version}`;
     }
     return version;
 }

package.json

@@ -8,16 +8,17 @@
   "private": true,
   "devDependencies": {
     "@theia/cli": "next",
+    "cross-env": "^7.0.2",
     "lerna": "^3.20.2",
     "rimraf": "^2.6.1",
     "tslint": "^5.5.0",
     "typescript": "^3.9.2"
   },
   "scripts": {
-    "prepare": "lerna run prepare && yarn download:plugins",
+    "prepare": "cross-env THEIA_ELECTRON_SKIP_REPLACE_FFMPEG=1 lerna run prepare && yarn download:plugins",
     "rebuild:browser": "theia rebuild:browser",
     "rebuild:electron": "theia rebuild:electron --modules \"@theia/node-pty\" nsfw native-keymap find-git-repositories grpc",
-    "start": "yarn --cwd ./browser-app start",
+    "start": "yarn rebuild:electron && yarn --cwd ./electron-app start",
     "watch": "lerna run watch --parallel",
     "test": "lerna run test",
     "download:plugins": "theia download:plugins"

yarn.lock

@@ -5882,6 +5882,13 @@ create-hmac@^1.1.0, create-hmac@^1.1.4, create-hmac@^1.1.7:
     safe-buffer "^5.0.1"
     sha.js "^2.4.8"
 
+cross-env@^7.0.2:
+  version "7.0.2"
+  resolved "https://registry.yarnpkg.com/cross-env/-/cross-env-7.0.2.tgz#bd5ed31339a93a3418ac4f3ca9ca3403082ae5f9"
+  integrity sha512-KZP/bMEOJEDCkDQAyRhu3RL2ZO/SUVrxQVI0G3YEQ+OLbRA3c6zgixe8Mq8a/z7+HKlNEjo8oiLUs8iRijY2Rw==
+  dependencies:
+    cross-spawn "^7.0.1"
+
 cross-spawn-async@^2.1.1:
   version "2.2.5"
   resolved "https://registry.yarnpkg.com/cross-spawn-async/-/cross-spawn-async-2.2.5.tgz#845ff0c0834a3ded9d160daca6d390906bb288cc"
@@ -5909,7 +5916,7 @@ cross-spawn@^6.0.0, cross-spawn@^6.0.5:
     shebang-command "^1.2.0"
     which "^1.2.9"
 
-cross-spawn@^7.0.0:
+cross-spawn@^7.0.0, cross-spawn@^7.0.1:
   version "7.0.3"
   resolved "https://registry.yarnpkg.com/cross-spawn/-/cross-spawn-7.0.3.tgz#f73a85b9d5d41d045551c177e2882d4ac85728a6"
   integrity sha512-iRDPJKUPVEND7dHPO8rkbOnPpyDygcDFtWjpeWNCgy8WP2rXcxXL8TskReQl6OrB2G7+UJrags1q15Fudc7G6w==