From e479b95d72bed6a50ae6a971598a18d8a7562f0d Mon Sep 17 00:00:00 2001 From: mcraa <6892971+mcraa@users.noreply.github.com> Date: Tue, 21 Feb 2023 13:39:28 +0100 Subject: [PATCH] patch: organize docs --- README.md | 19 ++++++- FAQ.md => docs/FAQ.md | 0 docs/MAINTAINERS.md | 81 +++++------------------------ docs/PUBLISHING.md | 97 ++++------------------------------- SUPPORT.md => docs/SUPPORT.md | 0 docs/USER-DOCUMENTATION.md | 11 ++-- 6 files changed, 45 insertions(+), 163 deletions(-) rename FAQ.md => docs/FAQ.md (100%) rename SUPPORT.md => docs/SUPPORT.md (100%) diff --git a/README.md b/README.md index 17f5f574..972b9ba6 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/FAQ.md b/docs/FAQ.md similarity index 100% rename from FAQ.md rename to docs/FAQ.md diff --git a/docs/MAINTAINERS.md b/docs/MAINTAINERS.md index d5579b82..cad7a26d 100644 --- a/docs/MAINTAINERS.md +++ b/docs/MAINTAINERS.md @@ -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/" -``` +Log in to cloudfront and upload the `rpm` and `deb` files. ### Dealing with a Problematic Release diff --git a/docs/PUBLISHING.md b/docs/PUBLISHING.md index e1e6d345..572f6303 100644 --- a/docs/PUBLISHING.md +++ b/docs/PUBLISHING.md @@ -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 RELEASE_TYPE=snapshot -make 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 diff --git a/SUPPORT.md b/docs/SUPPORT.md similarity index 100% rename from SUPPORT.md rename to docs/SUPPORT.md diff --git a/docs/USER-DOCUMENTATION.md b/docs/USER-DOCUMENTATION.md index 6e9084d7..3274b202 100644 --- a/docs/USER-DOCUMENTATION.md +++ b/docs/USER-DOCUMENTATION.md @@ -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. \ No newline at end of file