Document project architecture, Android modernization path, and codebase improvement roadmap

.github/workflows/build-apk.yml

@@ -0,0 +1,55 @@
+name: build-apk
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'
+  pull_request:
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4.1.7
+
+      - name: Set up Java
+        uses: actions/setup-java@v4.2.1
+        with:
+          distribution: temurin
+          java-version: '17'
+
+      - name: Set up Android SDK
+        uses: android-actions/setup-android@v3.2.2
+
+      - name: Install required SDK components
+        run: |
+          yes | sdkmanager "platforms;android-34" "build-tools;34.0.0"
+
+      - name: Build debug APK
+        run: |
+          chmod +x ./gradlew
+          ./gradlew :app:assembleDebug
+          mkdir -p bin
+          cp app/build/outputs/apk/debug/app-debug.apk bin/ve-debug.apk
+
+      - name: Upload APK artifact
+        uses: actions/upload-artifact@v4.3.3
+        with:
+          name: ve-debug-apk
+          path: ${{ github.workspace }}/bin/ve-debug.apk
+          if-no-files-found: error
+
+      - name: Publish release asset on tag
+        if: startsWith(github.ref, 'refs/tags/v')
+        uses: softprops/action-gh-release@v2.0.8
+        with:
+          files: |
+            ${{ github.workspace }}/bin/ve-debug.apk

.gitignore

@@ -1,10 +1,13 @@
 *~
 bin/
 gen/
+obj/
 .project
 .settings/
+.gradle/
+app/build/
+build/
 
 res/values-*/strings.xml
 
 various/play-featured-graphics.png
-

AndroidManifest.xml

@@ -1,29 +1,20 @@
 <?xml version="1.0" encoding="utf-8"?>
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    package="eu.pryds.ve"
-    android:versionCode="8"
-    android:versionName="0.1.4" >
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" >
 
-    <uses-permission
-        android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
-
-    <uses-sdk
-        android:minSdkVersion="14"
-        android:targetSdkVersion="18" />
-
     <application
         android:allowBackup="true"
         android:backupAgent="eu.pryds.ve.VeBackupAgent"
         android:icon="@drawable/ic_launcher"
         android:label="@string/app_name"
-        android:theme="@android:style/Theme.Holo.Light" >
+        android:theme="@style/AppTheme" >
 
         <meta-data
             android:name="com.google.android.backup.api_key"
             android:value="AEdPqrEAAAAILlof6VZJzaJUtfLSNUh6Add5cYguHu2b6I5K-Q" />
 
         <activity
             android:name="eu.pryds.ve.MainActivity"
+            android:exported="true"
             android:label="@string/app_name" >
             <intent-filter>
                 <action android:name="android.intent.action.MAIN" />
@@ -33,27 +24,15 @@
         </activity>
         <activity
             android:name="eu.pryds.ve.SettingsActivity"
+            android:exported="false"
             android:label="@string/title_activity_settings"
             android:parentActivityName="eu.pryds.ve.MainActivity" >
-            <meta-data
-                android:name="android.support.PARENT_ACTIVITY"
-                android:value="eu.pryds.ve.MainActivity" />
-        </activity>
-        <activity
-            android:name="eu.pryds.ve.FileChooser"
-            android:label="@string/title_activity_file_chooser"
-            android:parentActivityName="eu.pryds.ve.MainActivity" >
-            <meta-data
-                android:name="android.support.PARENT_ACTIVITY"
-                android:value="eu.pryds.ve.MainActivity" />
         </activity>
         <activity
             android:name="eu.pryds.ve.DonateActivity"
+            android:exported="false"
             android:label="@string/title_activity_donate"
             android:parentActivityName="eu.pryds.ve.MainActivity" >
-            <meta-data
-                android:name="android.support.PARENT_ACTIVITY"
-                android:value="eu.pryds.ve.MainActivity" />
         </activity>
     </application>
 

README.md

@@ -13,6 +13,130 @@ Vé is named after one of [Odin's two brothers](http://en.wikipedia.org/wiki/Vil
 
 Vé is open source software, released under the GPL licence, which means you can use it for free, for personal or other purposes. You can even redistribute it, modified or not, provided you do so under the same licence, which means you have to provide your source files for any changes. You can read the [full licence text here](https://github.com/pryds/ve/blob/master/COPYING).
 
+Project structure
+-----------------
+
+At a high level, the app is made of:
+
+* `MainActivity`: the main translation editor screen.
+* `TranslatableString` and `TranslatableStringCollection`: PO parsing/writing model layer.
+* `SettingsActivity`/`SettingsFragment`: translator metadata preferences.
+* `res/`: layouts, strings, menus and drawables.
+
+Manual smoke test (baseline)
+----------------------------
+
+Run this checklist after each small modernization change:
+
+1. **Open PO file**
+   * Use **Open file** and load a valid `.po` file.
+   * Confirm original/translated text areas are populated.
+2. **Navigate strings**
+   * Tap **Previous** and **Next**.
+   * Confirm string number and content update correctly.
+3. **Edit translation**
+   * Change text in translated field.
+   * Confirm metadata counters update.
+4. **Save file**
+   * Tap **Save file** and verify success toast.
+   * Reopen the file and verify edited text persists.
+5. **Settings read/write**
+   * Open **Settings**, edit translator fields, save/back out.
+   * Return and confirm values persist and are used on save.
+
+Current architecture map
+------------------------
+
+* **UI layer (Java + framework widgets)**:
+  * `MainActivity` drives the translation editor.
+  * `SettingsActivity` + `SettingsFragment` handle translator identity/preferences.
+* **Model/parsing layer**:
+  * `TranslatableString` stores PO entry/header data.
+  * `TranslatableStringCollection` parses PO files and serializes back to PO output.
+* **Resources/config**:
+  * `res/layout/activity_main.xml` is the primary editor screen.
+  * `res/menu/main_activity_actions.xml` defines top app actions.
+* **Build system**:
+  * Gradle-based project (`settings.gradle`, root `build.gradle`, `app/build.gradle`).
+
+Current limitations
+-------------------
+
+* File parsing/saving is still done on the main thread (can cause UI jank on large files).
+* Storage now uses SAF document URIs for open/save flows.
+* `MainActivity` contains multiple responsibilities (navigation, editing, persistence trigger, UI state).
+* Automated tests are still limited; manual smoke testing remains important.
+
+Modernization roadmap (incremental)
+-----------------------------------
+
+1. **UI polish without behavior changes**
+   * Improve spacing/typography/section labeling on main editor.
+2. **MainActivity maintainability refactor**
+   * Cache views, split screen-update helpers, preserve current behavior.
+3. **Editor UX improvements**
+   * Avoid unnecessary text resets, preserve cursor position, clarify plural-form state.
+4. **Architecture and async improvements**
+   * Move parse/save work off main thread and continue decoupling UI/model responsibilities.
+
+How to modernize Vé for newer Android versions
+----------------------------------------------
+
+This codebase now builds with Gradle, targets Android API level 34 (`targetSdk 34`), and uses a modern minimum API level 24 (`minSdk 24`).
+
+1. **Maintain modern Android baseline**
+   * Keep dependencies and build tooling current.
+2. **Continue modern platform cleanup**
+   * Replace remaining legacy utilities and disabled legacy features.
+3. **Run compatibility validation**
+    * Test on recent Android versions/emulators (Android 12, 13, 14+) and verify open/edit/save PO flows.
+
+How to improve the codebase
+---------------------------
+
+For the highest long-term quality and maintainability:
+
+* Add automated testing (unit tests for PO parser and serialization, plus instrumentation tests for file open/save flows).
+* Move parsing/saving work off the main thread to avoid UI jank on large files.
+* Introduce architecture boundaries (for example ViewModel + repository-style separation) to reduce Activity complexity.
+* Continue reducing synchronous file/parse work on UI thread and validate UX on large files.
+* Add static quality gates (Android Lint, CI workflow, formatting/lint checks).
+* Audit and remove dead/disabled features or fully modernize them (for example legacy in-app billing/backups).
+
+Build/testing quick start (Gradle)
+----------------------------------
+
+This repository now uses Gradle (`gradlew`, root `build.gradle`, `app/build.gradle`) as the build system.
+
+1. Configure an Android SDK path using one of:
+   * `local.properties` with `sdk.dir=/absolute/path/to/android-sdk`
+   * `ANDROID_HOME`
+   * `ANDROID_SDK_ROOT`
+2. Ensure your SDK contains:
+   * `platforms;android-34`
+   * `build-tools;34.0.0`
+   * App currently uses `targetSdkVersion` 34 and `minSdk` 24.
+   * File open/save flows use SAF-based document URIs.
+3. Run:
+   * `./gradlew :app:assembleDebug` to build a debug APK
+   * Output APK path: `app/build/outputs/apk/debug/app-debug.apk`
+   * Debug package name is `eu.pryds.ve.debug` (via `applicationIdSuffix ".debug"`), so it can install alongside release builds and avoid update/signature conflicts.
+
+APK exposure for testing (artifact/release)
+-------------------------------------------
+
+This repository now includes GitHub Actions workflow:
+
+* Workflow file: `.github/workflows/build-apk.yml`
+* Trigger manually from **Actions → build-apk → Run workflow**, or via pull requests/pushes.
+* Download the APK from workflow artifacts named **ve-debug-apk**.
+* If you push a tag like `v0.1.5`, the workflow also uploads `ve-debug.apk` as a release asset.
+
+Install notes for debug APKs
+----------------------------
+
+If Android shows **“invalid package”** while installing a debug APK over an existing install, uninstall the previously installed app variant first and then install the new APK. This typically happens when signatures differ between old and new builds, or when installing a build with a different applicationId/package variant.
+
 Contributing to Vé
 ------------------
 
@@ -25,3 +149,16 @@ Donations of any amount that you see fit are kindly accepted through Bitcoin add
 
 ![Donate Bitcoins](https://raw.github.com/pryds/ve/master/various/ve-donations-qr.png)
 
+Contributor workflow (step-by-step)
+-----------------------------------
+
+1. **Sync and branch**
+   * Pull latest changes and create a focused branch for one small change set.
+2. **Build**
+   * Run `./gradlew :app:assembleDebug`.
+3. **Run targeted checks**
+   * Run any relevant existing checks for your change area.
+4. **Install and verify**
+   * Install debug APK and execute the **Manual smoke test (baseline)** checklist above.
+5. **Submit small PR**
+   * Keep PR scope narrow (one modernization slice), include test notes and smoke-test results.

app/build.gradle

@@ -0,0 +1,53 @@
+apply plugin: 'com.android.application'
+
+android {
+    namespace 'eu.pryds.ve'
+    compileSdk 34
+
+    defaultConfig {
+        applicationId "eu.pryds.ve"
+        minSdk 24
+        targetSdk 34
+        versionCode 9
+        versionName "0.1.5"
+    }
+
+    sourceSets {
+        main {
+            manifest.srcFile '../AndroidManifest.xml'
+            java.srcDirs = ['../src']
+            res.srcDirs = ['../res']
+            assets.srcDirs = ['../assets']
+            jniLibs.srcDirs = ['../libs']
+            aidl.srcDirs = ['../src']
+        }
+    }
+
+    buildFeatures {
+        aidl true
+    }
+
+    buildTypes {
+        debug {
+            applicationIdSuffix ".debug"
+            versionNameSuffix "-debug"
+        }
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), '../proguard-project.txt'
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+}
+
+dependencies {
+    implementation fileTree(dir: '../libs', include: ['*.jar'])
+    implementation 'androidx.activity:activity:1.9.3'
+    implementation 'androidx.appcompat:appcompat:1.7.0'
+    implementation 'androidx.fragment:fragment:1.8.2'
+    implementation 'androidx.preference:preference:1.2.1'
+}

build.gradle

@@ -0,0 +1,22 @@
+buildscript {
+    def agpVersion = project.findProperty("androidGradlePluginVersion") ?: "8.4.2"
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath "com.android.tools.build:gradle:${agpVersion}"
+    }
+}
+
+allprojects {
+    repositories {
+        google()
+        mavenCentral()
+    }
+
+    configurations.configureEach {
+        exclude group: 'org.jetbrains.kotlin', module: 'kotlin-stdlib-jdk7'
+        exclude group: 'org.jetbrains.kotlin', module: 'kotlin-stdlib-jdk8'
+    }
+}

gradle.properties

@@ -0,0 +1,5 @@
+org.gradle.jvmargs=-Xmx2g -Dfile.encoding=UTF-8
+android.useAndroidX=true
+androidGradlePluginVersion=8.4.2
+# Keep legacy switch-case over R.id working: nonFinalResIds=false => generate final IDs.
+android.nonFinalResIds=false

gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.10.2-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists