Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

patch: update documentation #4214

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 18 additions & 3 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
-------------------
Expand Down Expand Up @@ -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
Expand All @@ -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
47 changes: 19 additions & 28 deletions docs/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/)
Expand All @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"hostDepencies" looks like a typo?


### Cloning the project

```sh
Expand All @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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.)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"not accidentally" ? 😆


- Write a concise commit message explaining your changes.

- If applies, write more descriptive information in the commit body.
Expand Down
4 changes: 2 additions & 2 deletions docs/FAQ.md
Original file line number Diff line number Diff line change
Expand Up @@ -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?

Expand Down
24 changes: 2 additions & 22 deletions docs/MAINTAINERS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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)
Expand Down Expand Up @@ -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/)
Expand Down
2 changes: 2 additions & 0 deletions docs/MANUAL-TESTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
---------------

Expand Down
21 changes: 7 additions & 14 deletions docs/PUBLISHING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
---------
Expand All @@ -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
---------------------------
Expand All @@ -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)
Loading