From 1e2bdfe511e7762bb6b2c79665176e093d67e5f8 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Tue, 29 Aug 2023 11:04:36 +0200 Subject: [PATCH 1/8] Add documentation to explain how to install the application from a Github release. --- docs/install_from_github_release.md | 55 +++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 docs/install_from_github_release.md diff --git a/docs/install_from_github_release.md b/docs/install_from_github_release.md new file mode 100644 index 0000000000..98fd6e4d30 --- /dev/null +++ b/docs/install_from_github_release.md @@ -0,0 +1,55 @@ +# Installing Element X Android from a Github Release. + +This document explain how to install Element X Android from a Github Release. + + + +* [Requirements](#requirements) +* [Steps](#steps) +* [I already have the application on my phone](#i-already-have-the-application-on-my-phone) + + + +## Requirements + +The Github release will contain an Android App Bundle (with `aab` extension) file, and not APKs like on the Element Android project. So there is some steps to perform to generate and signed the APKs from the App Bundle. The generated APKs will then be selected depending on your phone configuration to be installed on a device (emulator or real device). + +The easiest way to do that is to use the debug signature that is shared between the developers and stored in the project. So we recommend to checkout the project first. Android Studio is not required, you can use the command line. + +You will also need to install [bundletool](https://developer.android.com/studio/command-line/bundletool). On MacOS, you can run the following command: + +```bash +brew install bundletool +``` + +## Steps + +1. Open the GitHub release that you want to install from https://github.com/vector-im/element-x-android/releases; +2. Download the asset `app-release-signed.aab` +3. Navigate to the folder where you cloned the project and run the following command: +```bash +bundletool build-apks --bundle= --output=./tmp/elementx.apks \ + --ks=./app/signature/debug.keystore --ks-pass=pass:android --ks-key-alias=androiddebugkey --key-pass=pass:android \ + --overwrite +``` +For instance: +```bash +bundletool build-apks --bundle=./tmp/Element/0.1.5/app-release-signed.aab --output=./tmp/elementx.apks \ + --ks=./app/signature/debug.keystore --ks-pass=pass:android --ks-key-alias=androiddebugkey --key-pass=pass:android \ + --overwrite +``` +4. Run an Android emulator, or connect a real device to your computer. +5. Install the APKs on the device: +```bash +bundletool install-apks --apks=./tmp/elementx.apks +``` + +That's it, the application should be installed on your device, you can start it from the launcher icon. + +## I already have the application on my phone + +If the application was already installed on your phone, there are several cases: + +- it was installed from the PlayStore, you will have to uninstall it first, because the signature will not match. +- it was installed from a previous GitHub release, this is like an application upgrade, so no need to uninstall the existing app. +- it was installed from a more recent GitHub release, you will have to uninstall it first. From 02e22b786905ec930b62cea5eeb0445431153154 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Tue, 29 Aug 2023 11:06:17 +0200 Subject: [PATCH 2/8] Release script: do not bundle the minimal app when checking if the project compiles locally. --- tools/release/release.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/release/release.sh b/tools/release/release.sh index 20005d2816..43d129fa26 100755 --- a/tools/release/release.sh +++ b/tools/release/release.sh @@ -143,7 +143,7 @@ git commit -a -m "Setting version for the release ${version}" printf "\n================================================================================\n" printf "Building the bundle locally first...\n" -./gradlew clean bundleRelease +./gradlew clean app:bundleRelease printf "\n================================================================================\n" printf "Running towncrier...\n" From 8403c24643c518a11fe9002b4e1a7d4d3229cfb6 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Tue, 29 Aug 2023 11:11:35 +0200 Subject: [PATCH 3/8] Release script: split APKs generation and APK deployment into 2 separate steps. --- tools/release/release.sh | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/tools/release/release.sh b/tools/release/release.sh index 43d129fa26..72d75735fd 100755 --- a/tools/release/release.sh +++ b/tools/release/release.sh @@ -269,19 +269,26 @@ printf "\n====================================================================== printf "The file ${signedBundlePath} has been signed and can be uploaded to the PlayStore!\n" printf "\n================================================================================\n" -read -p "Do you want to install the application to your device? Make sure there is a connected device first. (yes/no) default to yes " doDeploy -doDeploy=${doDeploy:-yes} +read -p "Do you want to build the APKs from the app bundle? You need to do this step if you want to install the application to your device. (yes/no) default to yes " doBuildApks +doBuildApks=${doBuildApks:-yes} -if [ ${doDeploy} == "yes" ]; then +if [ ${doBuildApks} == "yes" ]; then printf "Building apks...\n" bundletool build-apks --bundle=${signedBundlePath} --output=${targetPath}/elementx.apks \ --ks=./app/signature/debug.keystore --ks-pass=pass:android --ks-key-alias=androiddebugkey --key-pass=pass:android \ --overwrite - printf "Installing apk for your device...\n" - bundletool install-apks --apks=${targetPath}/elementx.apks - read -p "Please run the application on your phone to check that the upgrade went well (no init sync, etc.). Press enter when it's done." + + read -p "Do you want to install the application to your device? Make sure there is one (and only one!) connected device first. (yes/no) default to yes " doDeploy + doDeploy=${doDeploy:-yes} + if [ ${doDeploy} == "yes" ]; then + printf "Installing apk for your device...\n" + bundletool install-apks --apks=${targetPath}/elementx.apks + read -p "Please run the application on your phone to check that the upgrade went well. Press enter when it's done." + else + printf "APK will not be deployed!\n" + fi else - printf "Apk will not be deployed!\n" + printf "APKs will not be generated!\n" fi printf "\n================================================================================\n" From ead323c9f22af44a4d174c187917b9e5a73ce8d3 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Tue, 29 Aug 2023 11:14:33 +0200 Subject: [PATCH 4/8] Release script: Add link to documentation to install the application from the GitHub release. --- tools/release/release.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/release/release.sh b/tools/release/release.sh index 72d75735fd..6d812b42b7 100755 --- a/tools/release/release.sh +++ b/tools/release/release.sh @@ -303,7 +303,7 @@ read -p ". Press enter when it's done. " printf "\n================================================================================\n" printf "Message for the Android internal room:\n\n" -message="@room Element X Android ${version} is ready to be tested. You can get it from https://github.com/vector-im/element-x-android/releases/tag/v${version}. Please report any feedback here. Thanks!" +message="@room Element X Android ${version} is ready to be tested. You can get it from https://github.com/vector-im/element-x-android/releases/tag/v${version}. Installation instructions can be found [here](https://github.com/vector-im/element-x-android/blob/develop/docs/install_from_github_release.md). Please report any feedback. Thanks!" printf "${message}\n\n" if [[ -z "${elementBotToken}" ]]; then From aafc5814ebf64deae8be1597457ed738021ebad8 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Tue, 29 Aug 2023 11:19:32 +0200 Subject: [PATCH 5/8] Release script: improve prompt messages. --- tools/release/release.sh | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/tools/release/release.sh b/tools/release/release.sh index 6d812b42b7..a5701ea5e1 100755 --- a/tools/release/release.sh +++ b/tools/release/release.sh @@ -150,7 +150,7 @@ printf "Running towncrier...\n" yes | towncrier build --version "v${version}" printf "\n================================================================================\n" -read -p "Check the file CHANGES.md consistency. It's possible to reorder items (most important changes first) or change their section if relevant. Also an opportunity to fix some typo, or rewrite things. Do not commit your change. Press enter when it's done." +read -p "Check the file CHANGES.md consistency. It's possible to reorder items (most important changes first) or change their section if relevant. Also an opportunity to fix some typo, or rewrite things. Do not commit your change. Press enter to continue. " # Get the changes to use it to create the GitHub release changelogUrlEncoded=`git diff CHANGES.md | grep ^+ | tail -n +2 | cut -c2- | jq -sRr @uri | sed s/\(/%28/g | sed s/\)/%29/g` @@ -168,7 +168,7 @@ fastlaneFile="4${versionMajor2Digits}${versionMinor2Digits}${versionPatch2Digits fastlanePathFile="./fastlane/metadata/android/en-US/changelogs/${fastlaneFile}" printf "Main changes in this version: TODO.\nFull changelog: https://github.com/vector-im/element-x-android/releases" > ${fastlanePathFile} -read -p "I have created the file ${fastlanePathFile}, please edit it and press enter when it's done." +read -p "I have created the file ${fastlanePathFile}, please edit it and press enter to continue. " git add ${fastlanePathFile} git commit -a -m "Adding fastlane file for version ${version}" @@ -200,7 +200,7 @@ sed "s/private const val versionPatch = .*/private const val versionPatch = ${ne rm ${versionsFileBak} printf "\n================================================================================\n" -read -p "I have updated the versions to prepare the next release, please check that the change are correct and press enter so I can commit." +read -p "I have updated the versions to prepare the next release, please check that the change are correct and press enter so I can commit. " printf "Committing...\n" git commit -a -m 'version++' @@ -263,7 +263,7 @@ printf "Version name: " bundletool dump manifest --bundle=${signedBundlePath} --xpath=/manifest/@android:versionName printf "\n" -read -p "Does it look correct? Press enter when it's done." +read -p "Does it look correct? Press enter to continue. " printf "\n================================================================================\n" printf "The file ${signedBundlePath} has been signed and can be uploaded to the PlayStore!\n" @@ -283,7 +283,7 @@ if [ ${doBuildApks} == "yes" ]; then if [ ${doDeploy} == "yes" ]; then printf "Installing apk for your device...\n" bundletool install-apks --apks=${targetPath}/elementx.apks - read -p "Please run the application on your phone to check that the upgrade went well. Press enter when it's done." + read -p "Please run the application on your phone to check that the upgrade went well. Press enter to continue. " else printf "APK will not be deployed!\n" fi @@ -299,7 +299,7 @@ printf "Then\n" printf " - copy paste the section of the file CHANGES.md for this release (if not there yet)\n" printf " - click on the 'Generate releases notes' button\n" printf " - Add the file ${signedBundlePath} to the GitHub release.\n" -read -p ". Press enter when it's done. " +read -p ". Press enter to continue. " printf "\n================================================================================\n" printf "Message for the Android internal room:\n\n" @@ -307,7 +307,7 @@ message="@room Element X Android ${version} is ready to be tested. You can get i printf "${message}\n\n" if [[ -z "${elementBotToken}" ]]; then - read -p "ELEMENT_BOT_MATRIX_TOKEN is not defined in the environment. Cannot send the message for you. Please send it manually, and press enter when it's done " + read -p "ELEMENT_BOT_MATRIX_TOKEN is not defined in the environment. Cannot send the message for you. Please send it manually, and press enter to continue. " else read -p "Send this message to the room (yes/no) default to yes? " doSend doSend=${doSend:-yes} From 58fcc0b23d85b9223b3d747aefc6b18e9c54c19f Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Tue, 29 Aug 2023 11:22:14 +0200 Subject: [PATCH 6/8] Grammar. --- docs/install_from_github_release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install_from_github_release.md b/docs/install_from_github_release.md index 98fd6e4d30..eec5586d82 100644 --- a/docs/install_from_github_release.md +++ b/docs/install_from_github_release.md @@ -1,6 +1,6 @@ # Installing Element X Android from a Github Release. -This document explain how to install Element X Android from a Github Release. +This document explains how to install Element X Android from a Github Release. From 6aa4cd061b919d1d33bffd65a8b281cd0a98c530 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Wed, 30 Aug 2023 12:48:33 +0200 Subject: [PATCH 7/8] Iterate and reformulate after PR review. --- docs/install_from_github_release.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/docs/install_from_github_release.md b/docs/install_from_github_release.md index eec5586d82..57363a617c 100644 --- a/docs/install_from_github_release.md +++ b/docs/install_from_github_release.md @@ -1,4 +1,4 @@ -# Installing Element X Android from a Github Release. +# Installing Element X Android from a Github Release This document explains how to install Element X Android from a Github Release. @@ -12,9 +12,18 @@ This document explains how to install Element X Android from a Github Release. ## Requirements -The Github release will contain an Android App Bundle (with `aab` extension) file, and not APKs like on the Element Android project. So there is some steps to perform to generate and signed the APKs from the App Bundle. The generated APKs will then be selected depending on your phone configuration to be installed on a device (emulator or real device). +The Github release will contain an Android App Bundle (with `aab` extension) file, unlike in the Element Android project where releases directly provide the APKs. So there are some steps to perform to generate and sign App Bundle APKs. An APK suitable for the targeted device will then be generated. -The easiest way to do that is to use the debug signature that is shared between the developers and stored in the project. So we recommend to checkout the project first. Android Studio is not required, you can use the command line. +The easiest way to do that is to use the debug signature that is shared between the developers and stored in the Element X Android project. So we recommend to clone the project first, to be able to use the debug signature it contains. But note that you can use any other signature. You don't need to install Android Studio, you will only need a shell terminal. + +You can clone the project by running: +```bash +git clone git@github.com:vector-im/element-x-android.git +``` +or +```bash +git clone https://github.com/vector-im/element-x-android.gi +``` You will also need to install [bundletool](https://developer.android.com/studio/command-line/bundletool). On MacOS, you can run the following command: @@ -24,7 +33,7 @@ brew install bundletool ## Steps -1. Open the GitHub release that you want to install from https://github.com/vector-im/element-x-android/releases; +1. Open the GitHub release that you want to install from https://github.com/vector-im/element-x-android/releases 2. Download the asset `app-release-signed.aab` 3. Navigate to the folder where you cloned the project and run the following command: ```bash @@ -38,7 +47,7 @@ bundletool build-apks --bundle=./tmp/Element/0.1.5/app-release-signed.aab --outp --ks=./app/signature/debug.keystore --ks-pass=pass:android --ks-key-alias=androiddebugkey --key-pass=pass:android \ --overwrite ``` -4. Run an Android emulator, or connect a real device to your computer. +4. Run an Android emulator, or connect a real device to your computer 5. Install the APKs on the device: ```bash bundletool install-apks --apks=./tmp/elementx.apks @@ -50,6 +59,6 @@ That's it, the application should be installed on your device, you can start it If the application was already installed on your phone, there are several cases: -- it was installed from the PlayStore, you will have to uninstall it first, because the signature will not match. +- it was installed from the PlayStore, you will have to uninstall it first because the signature will not match. - it was installed from a previous GitHub release, this is like an application upgrade, so no need to uninstall the existing app. - it was installed from a more recent GitHub release, you will have to uninstall it first. From 1ea4559625b64eeb913159d1c7b22d017a30c6fe Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Thu, 31 Aug 2023 15:41:48 +0200 Subject: [PATCH 8/8] fix typo in git url. Co-authored-by: Florian Renaud --- docs/install_from_github_release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install_from_github_release.md b/docs/install_from_github_release.md index 57363a617c..de395f737a 100644 --- a/docs/install_from_github_release.md +++ b/docs/install_from_github_release.md @@ -22,7 +22,7 @@ git clone git@github.com:vector-im/element-x-android.git ``` or ```bash -git clone https://github.com/vector-im/element-x-android.gi +git clone https://github.com/vector-im/element-x-android.git ``` You will also need to install [bundletool](https://developer.android.com/studio/command-line/bundletool). On MacOS, you can run the following command: