balena-io · aethernet · Apr 27, 2024 · lurch · Apr 28, 2024 · lurch
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -11,12 +11,14 @@ This is a non exhaustive list of the major frameworks, libraries, and other
 technologies used in Etcher that you should become familiar with:
 
 - [Electron][electron]
+- [Pkg][pkg]
 - [NodeJS][nodejs]
 - [Redux][redux]
 - [ImmutableJS][immutablejs]
+- [WS][ws]
 - [Sass][sass]
 - [Mocha][mocha]
-- [JSDoc][jsdoc]
+- [wdio][wdio]
 
 Module architecture
 -------------------
@@ -49,7 +51,18 @@ a system drive.
 This is the *"main repository"*, from which you're reading this from, which is
 basically the front-end and glue for all previously listed projects.
 
-Summary
+GUI & Util
+----------
+Etcher is split in two executables:
+- GUI (Electron/React/Redux/Rendition)
+- Util (Pkg/Etcher-sdk)
+
+The `GUI` is handling all the interaction with the user and will spawn the `Util`
+to handle the scanning and flashing process.
+
+`Util` will start a local Websocket server that `GUI` will connect to.
+
+Contrib
 -------
 
 We always welcome contributions to Etcher as well as our documentation. If you
@@ -67,4 +80,6 @@ be documented instead!
 [immutablejs]: http://facebook.github.io/immutable-js/
 [sass]: http://sass-lang.com
 [mocha]: http://mochajs.org
-[jsdoc]: http://usejsdoc.org
+[pkg]: https://github.com/yao-pkg/pkg
+[wdio]: https://webdriver.io
+[ws]: https://www.npmjs.com/package/ws
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -17,41 +17,22 @@ Developing
 
 #### Common
 
-- [NodeJS](https://nodejs.org) (at least v16.11)
-- [Python 3](https://www.python.org)
-- [jq](https://stedolan.github.io/jq/)
-- [curl](https://curl.haxx.se/)
-- [npm](https://www.npmjs.com/)
-
-```sh
-pip install -r requirements.txt
-```
-
-You might need to run this with `sudo` or administrator permissions.
+- [NodeJS](https://nodejs.org) (check the required `enginge` version in `package.json`)
+- [Node-gyp](https://github.com/nodejs/node-gyp?tab=readme-ov-file#installation) toolchain (see their docs for your system requirements)
 
 #### Windows
 
-- [NSIS v2.51](http://nsis.sourceforge.net/Main_Page) (v3.x won't work)
 - Either one of the following:
  - [Visual C++ 2019 Build Tools](https://visualstudio.microsoft.com/vs/features/cplusplus/) containing standalone compilers, libraries and scripts
  - The [windows-build-tools](https://github.com/felixrieseberg/windows-build-tools#windows-build-tools) should be installed along with NodeJS
  - [Visual Studio Community 2019](https://visualstudio.microsoft.com/vs/) (free) (other editions, like Professional and Enterprise, should work too)
  **NOTE:** Visual Studio doesn't install C++ by default. You have to rerun the
  setup, select "Modify" and then check `Visual C++ -> Common Tools for Visual
  C++` (see http://stackoverflow.com/a/31955339)
-- [MinGW](http://www.mingw.org)
 
 You might need to `npm config set msvs_version 2019` for node-gyp to correctly detect
 the version of Visual Studio you're using (in this example VS2019).
 
-The following MinGW packages are required:
-
-- `msys-make`
-- `msys-unzip`
-- `msys-zip`
-- `msys-bash`
-- `msys-coreutils`
-
 #### macOS
 
 - [Xcode](https://developer.apple.com/xcode/)
@@ -63,6 +44,8 @@ as well.
 
 - `libudev-dev` for libusb (for example install with `sudo apt install libudev-dev`, or on fedora `systemd-devel` contains the required package)
 
+- Check the `hostDepencies` in `package.json` for the requirements for `debian`, you might need to adapt the package list for other distribution.
+
 ### Cloning the project
 
 ```sh
@@ -84,17 +67,18 @@ Testing
 
 To run the test suite, run the following command:
 
+For the unit tests
 ```sh
-npm test
+npm wdio --suite gui --suite shared
 ```
 
-Given the nature of this application, not everything can be unit tested. For
-example:
+For the e2e tests you need: 
+- to provide a test device (`TARGET_DRIVE`), this can be a virtual drive (check the `.github/actions/test/action.yml` for example on how to create the virtual drives for differnet OS). If you use a virtual drive on Mac, you'll need to set `ETCHER_INCLUDE_VIRTUAL_DRIVES` in the ENV.
+- to run with administator privileges (as the request cannot be automated). Use `sudo` (or `runas` on windows)
 
-- The writing operating on real raw devices.
-- Platform inconsistencies.
-- Style changes.
-- Artwork.
+```sh
+sudo npm wdio --suite e2e
+```
 
 We encourage our contributors to test the application on as many operating
 systems as they can before sending a pull request.
@@ -111,6 +95,7 @@ Updating a dependency
 ---------------------
 
 - Install new version of dependency using npm
+- Run all tests (including e2e)
 - Commit *both* `package.json` and `npm-shrinkwrap.json`.
 
 Diffing Binaries
@@ -146,6 +131,12 @@ Sending a pull request
 
 When sending a pull request, consider the following guidelines:
 
+- Double check that your commits follows the [COMMIT-GUIDELINES.md][COMMIT-GUIDELINES]
+
+- Run the linter & prettifier with `npm run prettify`
+
+- Check that you're accidentally pushing some unrelated changes (i.e. formating, etc.)
+
 - Write a concise commit message explaining your changes.
 
 - If applies, write more descriptive information in the commit body.

diff --git a/docs/FAQ.md b/docs/FAQ.md
@@ -41,9 +41,9 @@ To solve these kinds of problems, we've collected [a list of fail-proof methods]
 
 Etcher requires an available [polkit authentication agent](https://wiki.archlinux.org/index.php/Polkit#Authentication_agents) in your system in order to show a secure password prompt dialog to perform elevation. Make sure you have one installed for the desktop environment of your choice.
 
-## May I run Etcher in older macOS versions?
+## Which OS versions are supported by Etcher?
 
-Etcher GUI is based on the [Electron](http://electron.atom.io/) framework, [which only supports macOS 10.10 and newer versions](https://github.com/electron/electron/blob/master/docs/tutorial/support.md#supported-platforms).
+Etcher GUI is based on the [Electron](http://electron.atom.io/) framework, [see their list of supported OS versions]. Note that as the time of writing, Windows 10, macOS Catalina and Ubuntu 18.04 are the lowest supported versions.
 
 ## Can I use the Flash With Etcher button on my site?
 

diff --git a/docs/MAINTAINERS.md b/docs/MAINTAINERS.md
@@ -12,7 +12,7 @@ Releasing
 - **pre-release** (default): A continues snapshot of current master, made by the CI services
 - **release**: Full releases
 
-Draft release is created from each PR, tagged with the branch name.
+Draft release is created from each PR, tagged with the branch name, only visible by balena team members.
 All merged PR will generate a new tag/version as a *pre-release*.
 Mark the pre-release as final when it is necessary, then distribute the packages in alternative channels as necessary.
 
@@ -32,9 +32,8 @@ Mark the pre-release as final when it is necessary, then distribute the packages
 #### Publishing
 
 - [Publish release draft on GitHub](https://github.com/balena-io/etcher/releases)
-- [Post release note to forums](https://forums.balena.io/c/etcher)
 - [Submit Windows binaries to Symantec for whitelisting](#submitting-binaries-to-symantec)
-- [Update the website](https://github.com/balena-io/etcher-homepage)
+- [Update the website](https://balena.io/etcher)
 - Wait 2-3 hours for analytics (Sentry, Amplitude) to trickle in and check for elevated error rates, or regressions
 - If regressions arise; pull the release, and release a patched version, else:
 - [Upload deb & rpm packages to Cloudfront](#uploading-packages-to-cloudfront)
@@ -71,35 +70,16 @@ npm run make
 
 Our CI will appropriately sign artifacts for macOS and some Windows targets.
 
-
-### Uploading packages to Cloudfront
-
-Log in to cloudfront and upload the `rpm` and `deb` files.
-
 ### Dealing with a Problematic Release
 
 There can be times where a release is accidentally plagued with bugs. If you
 released a new version and notice the error rates are higher than normal, then
 revert the problematic release as soon as possible, until the bugs are fixed.
 
-You can revert a version by deleting its builds from the S3 bucket and Bintray.
-Refer to the `Makefile` for the up to date information about the S3 bucket
-where we push builds to, and get in touch with the balena.io operations team to
-get write access to it.
-
 The Etcher update notifier dialog and the website only show the a certain
 version if all the expected files have been uploaded to it, so deleting a
 single package or two is enough to bring down the whole version.
 
-Use the following command to delete files from S3:
-
-```bash
-aws s3api delete-object --bucket <bucket name> --key <file name>
-```
-
-The Bintray dashboard provides an easy way to delete a version's files.
-
-
 ### Submitting binaries to Symantec
 
 - [Report a Suspected Erroneous Detection](https://submit.symantec.com/false_positive/standard/)

diff --git a/docs/MANUAL-TESTING.md b/docs/MANUAL-TESTING.md
@@ -4,6 +4,8 @@ Manual Testing
 This document describes a high-level script of manual tests to check for. We
 should aim to replace items on this list with automated Spectron test cases.
 
+Note that this should eventually be automated and move to the e2e tests.
+
 Image Selection
 ---------------
 

diff --git a/docs/PUBLISHING.md b/docs/PUBLISHING.md
@@ -27,11 +27,12 @@ packaging for OS X.
 
 ### Windows
 
-1. Get access to our code signing certificate and decryption key as a balena.io
-employee by asking for it from the relevant people.
+Since 2023, Microsoft requires all signing key to be store on hardware modules.
+Because of this, we now use a cloud-hsm product to sign Etcher.
+The required keys are set by balena operation on the Github CI.
 
-2. Place the certificate in the root of the Etcher repository naming it
-`certificate.p12`.
+The application will be signed automatically using the proper procss when
+packaging for Windows.
 
 Packaging
 ---------
@@ -51,9 +52,7 @@ The resulting artifacts can be found in `out/make`.
 Publishing to Cloudfront
 ---------------------
 
-We publish GNU/Linux Debian packages to [Cloudfront][cloudfront].
-
-Log in to cloudfront and upload the `rpm` and `deb` files.
+We currently don't publish GNU/Linux Debian or Fedora packages.
 
 Publishing to Homebrew Cask
 ---------------------------
@@ -67,16 +66,10 @@ Publishing to Homebrew Cask
 Announcing
 ----------
 
-Post messages to the [Etcher forum][balena-forum-etcher] announcing the new version
-of Etcher, and including the relevant section of the Changelog.
-
-[aws-cli]: https://aws.amazon.com/cli
-[cloudfront]: https://cloudfront.com
 [etcher-cask-file]: https://github.com/caskroom/homebrew-cask/blob/master/Casks/balenaetcher.rb
 [homebrew-cask]: https://github.com/caskroom/homebrew-cask
-[balena-forum-etcher]: https://forums.balena.io/c/etcher
 [github-releases]: https://github.com/balena-io/etcher/releases
 
 Updating EFP / Success-Banner
 -----------------------------
-Etcher Featured Project is automatically run based on an algorithm which promoted projects from the balena marketplace which have been contributed by the community, the algorithm prioritises projects which give uses the best experience. Editing both EFP and the Etcher Success-Banner can only be done by someone from balena, instruction are on the [Etcher-EFP repo (private)](https://github.com/balena-io/etcher-efp)
+Etcher Featured Project is automatically run based on an algorithm which promoted projects from the balena marketplace which have been contributed by the community, the algorithm prioritises projects which give users the best experience. Editing both EFP and the Etcher Success-Banner can only be done by someone from balena, instruction are on the [Etcher-EFP repo (private)](https://github.com/balena-io/etcher-efp)