jeans/etcher
jeans/etcher
1
0
Fork 0
mirror of https://github.com/balena-io/etcher.git synced 2025-04-19 12:57:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

patch: organize docs

Browse Source
This commit is contained in:
mcraa 2023-02-21 13:39:28 +01:00
parent 926ff2b754
commit e479b95d72
6 changed files with 45 additions and 163 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
README.md
View File

@ -53,9 +53,10 @@ confidence.
2. Update and install:
```sh
sudo apt-get update
sudo apt-get update #you can use apt instead of apt-get as well
sudo apt-get install balena-etcher-electron
```
>Note: after v1.7.9 the package name changed to `balena-etcher` (no electron at the end)
##### Uninstall
@ -87,6 +88,7 @@ apt-get update
```sh
sudo dnf install -y balena-etcher-electron
```
>Note: after v1.7.9 the package name changed to `balena-etcher` (no electron at the end)
###### Uninstall
@ -110,6 +112,7 @@ rm /etc/yum.repos.d/balena-etcher-source.repo
```sh
sudo yum install -y balena-etcher-electron
```
>Note: after v1.7.9 the package name changed to `balena-etcher` (no electron at the end)
###### Uninstall
@ -134,6 +137,7 @@ rm /etc/yum.repos.d/balena-etcher-source.repo
sudo zypper up
sudo zypper install balena-etcher-electron
```
>Note: after v1.7.9 the package name changed to `balena-etcher` (no electron at the end)
##### Uninstall
@ -169,6 +173,19 @@ yay -S balena-etcher
```sh
yay -R balena-etcher
```
#### WinGet (Windows)
This package is updated by [gh-action](https://github.com/vedantmgoyal2009/winget-releaser), and is kept up to date automatically.
```sh
winget install balenaEtcher #or Balena.Etcher
```
##### Uninstall
```sh
winget uninstall balenaEtcher
```
#### Chocolatey (Windows)

0
FAQ.md → docs/FAQ.md
View File

81
docs/MAINTAINERS.md
View File

@ -8,10 +8,14 @@ Releasing
### Release Types
- **snapshot** (default): A continues snapshot of current master, made by the CI services
- **production**: Full releases
- **draft**: A continues snapshot of current master, made by the CI services
- **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.
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.
### Flight Plan
#### Preparation
@ -33,9 +37,8 @@ Releasing
- [Update the website](https://github.com/balena-io/etcher-homepage)
- 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 Bintray](#uploading-packages-to-bintray)
- [Upload build artifacts to Amazon S3](#uploading-binaries-to-amazon-s3)
- Post changelog with `#release-notes` tag on Flowdock
- [Upload deb & rpm packages to Cloudfront](#uploading-packages-to-cloudfront)
- Post changelog with `#release-notes` tag on internal chat
- If this release packs noteworthy major changes:
- Write a blog post about it, and / or
- Write about it to the Etcher mailing list
@ -57,46 +60,16 @@ export ANALYTICS_AMPLITUDE_TOKEN="xxxxxx"
**NOTE:** Make sure to adjust the path as necessary (here the Etcher repository has been cloned to `/home/$USER/code/etcher`)
```bash
./scripts/build/docker/run-command.sh -r x64 -s . -c "make distclean"
```
##### Generating artifacts
```bash
# x64
# Build Debian packages
./scripts/build/docker/run-command.sh -r x64 -s . -c "make electron-develop && make RELEASE_TYPE=production electron-installer-debian"
# Build RPM packages
./scripts/build/docker/run-command.sh -r x64 -s . -c "make electron-develop && make RELEASE_TYPE=production electron-installer-redhat"
# Build AppImages
./scripts/build/docker/run-command.sh -r x64 -s . -c "make electron-develop && make RELEASE_TYPE=production electron-installer-appimage"
# x86
# Build Debian packages
./scripts/build/docker/run-command.sh -r x86 -s . -c "make electron-develop && make RELEASE_TYPE=production electron-installer-debian"
# Build RPM packages
./scripts/build/docker/run-command.sh -r x86 -s . -c "make electron-develop && make RELEASE_TYPE=production electron-installer-redhat"
# Build AppImages
./scripts/build/docker/run-command.sh -r x86 -s . -c "make electron-develop && make RELEASE_TYPE=production electron-installer-appimage"
```
The artifacts are generated by the CI and published as draft-release or pre-release.
`electron-builder` is used to create the packaged application.
#### Mac OS
**ATTENTION:** For production releases you'll need the code-signing key,
and set `CSC_NAME` to generate signed binaries on Mac OS.
```bash
make electron-develop
# Build the zip
make RELEASE_TYPE=production electron-installer-app-zip
# Build the dmg
make RELEASE_TYPE=production electron-installer-dmg
```
#### Windows
**ATTENTION:** For production releases you'll need the code-signing key,
@ -105,38 +78,10 @@ and set `CSC_LINK`, and `CSC_KEY_PASSWORD` to generate signed binaries on Window
**NOTE:**
- Keep in mind to also generate artifacts for x86, with `TARGET_ARCH=x86`.
```bash
make electron-develop
# Build the Portable version
make RELEASE_TYPE=production electron-installer-portable
# Build the Installer
make RELEASE_TYPE=production electron-installer-nsis
```
### Uploading packages to Cloudfront
### Uploading packages to Bintray
```bash
export BINTRAY_USER="username@account"
export BINTRAY_API_KEY="youruserapikey"
```
```bash
./scripts/publish/bintray.sh -c "etcher" -t "production" -v "1.2.1" -o "etcher" -p "debian" -y "debian" -r "x64" -f "dist/etcher-electron_1.2.1_amd64.deb"
./scripts/publish/bintray.sh -c "etcher" -t "production" -v "1.2.1" -o "etcher" -p "debian" -y "debian" -r "x86" -f "dist/etcher-electron_1.2.1_i386.deb"
./scripts/publish/bintray.sh -c "etcher" -t "production" -v "1.2.1" -o "etcher" -p "redhat" -y "redhat" -r "x64" -f "dist/etcher-electron-1.2.1.x86_64.rpm"
./scripts/publish/bintray.sh -c "etcher" -t "production" -v "1.2.1" -o "etcher" -p "redhat" -y "redhat" -r "x86" -f "dist/etcher-electron-1.2.1.i686.rpm"
```
### Uploading binaries to Amazon S3
```bash
export S3_KEY="..."
```
```bash
./scripts/publish/aws-s3.sh -b "balena-production-downloads" -v "1.2.1" -p "etcher" -f "dist/<filename>"
```
Log in to cloudfront and upload the `rpm` and `deb` files.
### Dealing with a Problematic Release

97
docs/PUBLISHING.md
View File

@ -7,44 +7,9 @@ systems.
Release Types
-------------
Etcher supports **production** and **snapshot** release types. Each is
published to a different S3 bucket, and production release types are code
signed, while snapshot release types aren't and include a short git commit-hash
as a build number. For example, `1.0.0-beta.19` is a production release type,
while `1.0.0-beta.19+531ab82` is a snapshot release type.
In terms of comparison: `1.0.0-beta.19` (production) < `1.0.0-beta.19+531ab82`
(snapshot) < `1.0.0-rc.1` (production) < `1.0.0-rc.1+7fde24a` (snapshot) <
`1.0.0` (production) < `1.0.0+2201e5f` (snapshot). Keep in mind that if you're
running a production release type, you'll only be prompted to update to
production release types, and if you're running a snapshot release type, you'll
only be prompted to update to other snapshot release types.
The build system creates (and publishes) snapshot release types by default, but
you can build a specific release type by setting the `RELEASE_TYPE` make
variable. For example:
```sh
make <target> RELEASE_TYPE=snapshot
make <target> RELEASE_TYPE=production
```
We can control the version range a specific Etcher version will consider when
showing the update notification dialog by tweaking the `updates.semverRange`
property of `package.json`.
Update Channels
---------------
Etcher has a setting to include the unstable update channel. If this option is
set, Etcher will consider both stable and unstable versions when showing the
update notifier dialog. Unstable versions are the ones that contain a `beta`
pre-release tag. For example:
- Production unstable version: `1.4.0-beta.1`
- Snapshot unstable version: `1.4.0-beta.1+7fde24a`
- Production stable version: `1.4.0`
- Snapshot stable version: `1.4.0+7fde24a`
Etcher supports **pre-release** and **final** release types as does Github. Each is
published to Github releases.
The release version is generated automatically from the commit messasges.
Signing
-------
@ -73,63 +38,19 @@ Packaging
The resulting installers will be saved to `dist/out`.
Run the following commands:
### OS X
Run the following commands on all platforms with the right arguments:
```sh
make electron-installer-dmg
make electron-installer-app-zip
./node_modules/electron-builder build <...>
```
### GNU/Linux
```sh
make electron-installer-appimage
make electron-installer-debian
```
### Windows
```sh
make electron-installer-zip
make electron-installer-nsis
```
Publishing to Bintray
Publishing to Cloudfront
---------------------
We publish GNU/Linux Debian packages to [Bintray][bintray].
We publish GNU/Linux Debian packages to [Cloudfront][cloudfront].
Make sure you set the following environment variables:
- `BINTRAY_USER`
- `BINTRAY_API_KEY`
Run the following command:
```sh
make publish-bintray-debian
```
Publishing to S3
----------------
- [AWS CLI][aws-cli]
Make sure you have the [AWS CLI tool][aws-cli] installed and configured to
access balena.io's production or snapshot S3 bucket.
Run the following command to publish all files for the current combination of
_platform_ and _arch_ (building them if necessary):
```sh
make publish-aws-s3
```
Also add links to each AWS S3 file in [GitHub Releases][github-releases]. See
[`v1.0.0-beta.17`](https://github.com/balena-io/etcher/releases/tag/v1.0.0-beta.17)
as an example.
Log in to cloudfront and upload the `rpm` and `deb` files.
Publishing to Homebrew Cask
---------------------------
@ -147,7 +68,7 @@ Post messages to the [Etcher forum][balena-forum-etcher] announcing the new vers
of Etcher, and including the relevant section of the Changelog.
[aws-cli]: https://aws.amazon.com/cli
[bintray]: https://bintray.com
[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

0
SUPPORT.md → docs/SUPPORT.md
View File

11
docs/USER-DOCUMENTATION.md
View File

@ -3,6 +3,11 @@ Etcher User Documentation
This document contains how-tos and FAQs oriented to Etcher users.
Config
------
Etcher's configuration is saved to the `config.json` file in the apps folder.
Not all the options are surfaced to the UI. You may edit this file to tweak settings even before launching the app.
Why is my drive not bootable?
-----------------------------
@ -219,10 +224,4 @@ macOS 10.10 (Yosemite) and newer versions][electron-supported-platforms].
[windows-iot-dashboard]: https://developer.microsoft.com/en-us/windows/iot/downloads
[woeusb]: https://github.com/slacka/WoeUSB
How can I simulate an update alert?
-----------------------------
You can set the ETCHER_FAKE_S3_LATEST_VERSION environment variable to a valid semver version (greater than the current version) to trick the application into thinking that what you put there is the latest available version, therefore causing the update notification dialog to be presented at startup.
Note that the value of the variable will be ignored if it doesn't match the release type of the current application version. For example, setting the variable to a production version (e.g. ETCHER_FAKE_S3_LATEST_VERSION=2.0.0) will be ignored if you're running a snapshot build, and vice-versa.
See [PUBLISHING](/docs/PUBLISHING.md) for more details about release types.