Provide documentation on which generated files / directories to commit to version control

[MoritzLost]

After following the tutorial and executing the init and build commands, you end up with a directory with a lot of files and directories:

.
|-- .gradle
|-- android.keystore
|-- app
|-- app-release-signed.apk
|-- app-release-unsigned-aligned.apk
|-- assetlinks.json
|-- build
|-- build.gradle
|-- gradle
|-- gradle.properties
|-- gradlew
|-- gradlew.bat
|-- settings.gradle
|-- store_icon.png
`-- twa-manifest.json

As a web developer who knows precious little about Android development, I'm not sure which of those files should go into version control and which are generated during the build step. I guess you don't commit the generated apk files? What about the app folder and all the different gradle files / directories? Finally, do I commit the keystore or put it securely in a key vault (not sure if that file is encrypted ...)?

I get that it's only tangentially related to this library, but I think it would be great for the documentation to have a couple of pointer for people unfamiliar with Android development:

• Which files should I commit to version control?
• On a new system, how do I reproduce the build from version control?
• How to handle the keystore file safely?

A related topic: I'm having trouble understanding all the different app signing methods and keystore formats (app signing key vs. upload key). A simple 'follow those steps to get the generated app in the play store' guide would be great, though I understand that's a lot of work. The current documentation just points to the app signing guide in the Android developer docs, but those prominently recommend using app signing by Google, and I have no idea how that relates to the signed app release generated by bubblewrap.

Since bubblewrap appears to be targeted towards non Android developers, it would be great to get some guidance for those topic in the documentation. Thanks!

[andreban]

Thanks for the feedback.

Which files should I commit to version control?

• You'd want to add the /build folder, .apk files, .aab files, the .gradle folder to .gitignore. You probably want to ignore android.keystore too, but you want to save that to a secure place. Would it be helpful if Bubblewrap generated .gitignore along with the other files?
• It's also interesting to note that, if you backup twa-manifest.json and android.keystore you will be able to regenerate the project by running bubblewrap update in the folder where they are. You can also do manual changes to twa-manifest.json and apply them to the generated project with bubblewrap update.

On a new system, how do I reproduce the build from version control?

• Install bubblewrap on the new system and configure the JDK and Android SDK
• Run bubblewrap build on the folder of the checkout.

How to handle the keystore file safely?

• I wouldn't add android.keystore to the version control, specially if that's something like GitHub. You probably want to store in a place where:
  • The file is backed-up so an HD crash won't get you in a place where you can't update your app anymore.
  • There's strict access control where only people who need to sign the APK for production and upload to the store have access.
• I'd also opt-in into App Signing so Play can manage the key for you - when opting into Play Signing, the key generated by Bubblewrap becomes the "upload key" and the "signing key" is managed by Play. Otherwise, the key generated by Bubblewrap is the "signing key". With App Signing, you can change the "upload key" if you lose it or if it leaks. Without App Signing, it isn't possible to update it and losing means you can't update your app on the store anymore.

Regarding understanding all the options, have you seen this document: https://developers.google.com/web/android/trusted-web-activity/quick-start. Let me know if it helps and what's missing, and we'll be happy to update with more information.

Btw, feel free to join us at one of those places to ask questions, give feedback, etc: https://github.com/GoogleChromeLabs/bubblewrap#community

[MoritzLost]

@andreban Thank you very much for the reply!

Would it be helpful if Bubblewrap generated .gitignore along with the other files?

I'd say that would be a useful addition. Though from my perspective it would be enough to add a section to the documentation which explains the generated directory strutcture / files a bit for users who don't regularly work with Android Studio / Android apps. Like a simple list of the generates files/directories which tells me what the file is and if one should commit or otherwise save it (like the keystore).

when opting into Play Signing, the key generated by Bubblewrap becomes the "upload key" and the "signing key" is managed by Play.

Thanks, that's the piece I was missing! Maybe that can be mentioned in the Quick Start guide as well? It's probably obvious to most people, but wasn't for me ^^

[hhimanshu]

Would it be helpful if Bubblewrap generated .gitignore along with the other files?

Oh yes, definitely. This would help us immensely.