diff --git a/docs/install_from_github_release.md b/docs/install_from_github_release.md new file mode 100644 index 0000000000..de395f737a --- /dev/null +++ b/docs/install_from_github_release.md @@ -0,0 +1,64 @@ +# Installing Element X Android from a Github Release + +This document explains 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, 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 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.git +``` + +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. diff --git a/tools/release/release.sh b/tools/release/release.sh index 20005d2816..a5701ea5e1 100755 --- a/tools/release/release.sh +++ b/tools/release/release.sh @@ -143,14 +143,14 @@ 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" 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,25 +263,32 @@ 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" 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 to continue. " + 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" @@ -292,15 +299,15 @@ 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" -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 - 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}