Sasedev/pgr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

0.1.3-alpha.2

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-28 10:41:03 +02:00
parent eaa9c399be
commit 1223a705c0
5 changed files with 397 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
docs/plans/009-V0_1_3_ANDROID_REEVALUATION_PLAN.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/009-V0_1_3_ANDROID_REEVALUATION_PLAN.md -->
<!-- version: 1 -->
<!-- version: 2 -->
# Plan 0.1.3 — réévaluation pratique Android
@@ -323,6 +323,48 @@ La classification initiale guide la réévaluation ; elle n'est pas une adoption
| Skeleton Tauri | `DEFER` | réservé à `0.1.4` |
| Adoption réelle de Games | `DEFER` | réservée à `0.1.5` |
## Décision après `alpha.1`
La gate opérateur de `alpha.1` est `PASS`. Les `48/48` tests Python, les trois audits Markdown, l'audit structurel de la tranche et les contrôles Git sont propres ; aucun `alpha.1.fix.N` n'est requis.
`alpha.2` peut donc appliquer les décisions déjà classifiées `ADOPT` / `OVERRIDE` pour les contrats Android de base, sans ouvrir le natif, le packaging de distribution ou les smokes réservés à `alpha.3`.
### Vérification Android officielle courante pour `alpha.2`
La documentation Android officielle courante a été vérifiée le `2026-09-28` sur les responsabilités touchées par cette tranche :
```text
https://developer.android.com/build/releases/agp-9-4-0-release-notes
https://developer.android.com/build
https://developer.android.com/build/jdks
https://developer.android.com/build/configure-app-module
https://developer.android.com/studio/publish/app-signing
```
Cette vérification confirme notamment :
- AGP possède une matrice de compatibilité explicite avec Gradle et le JDK de build ; AGP `9.4.0` requiert actuellement au minimum Gradle `9.6.0` et JDK `17`, ce qui confirme la cohérence du corpus Games sans transformer ces valeurs en minima PGR ;
- le JDK qui exécute Gradle/AGP est distinct du niveau de langage ou bytecode du code Java ; cette séparation reste nécessaire même lorsqu'un projet Android ne contient aucun source Java ;
- `compileSdk`, `targetSdk` et `minSdk` ont des responsabilités distinctes : APIs disponibles à la compilation, comportements/runtime ciblés et plus ancien niveau Android réellement supporté ;
- `namespace` et `applicationId` sont deux propriétés distinctes ; les garder identiques est le cas courant, mais leur divergence peut être volontaire et doit rester explicite ;
- `local.properties` est réservé aux propriétés locales de l'environnement Android/AGP et doit rester hors du contrôle de version ; des propriétés locales propres au projet doivent utiliser un mécanisme séparé ;
- les clés et mots de passe de signing sont des secrets ; le debug keystore généré par les outils reste un état local et ne constitue pas une identité de release à versionner.
La vérification 16 KB n'est pas absorbée ici : elle reste explicitement réservée à `alpha.3`, avec sa propre confrontation aux exigences de distribution officielles courantes.
### Scope arrêté pour `alpha.2`
La tranche révise uniquement `610-ANDROID.md` pour :
1. retirer du layout d'exemple toute présentation implicite du Wrapper comme élément obligatoire ;
2. rendre Android neutre quant au langage applicatif et composer `520-JAVA.md` seulement lorsque du Java est réellement présent ;
3. séparer clairement JDK de build AGP/Gradle et niveau Java du code ;
4. reformuler `minSdk` comme contrat produit explicite, sans objectif artificiel de valeur la plus basse ;
5. expliciter la séparation `namespace` / `applicationId` ;
6. consolider le rôle de `local.properties`, des propriétés partagées et du signing sans recopier les owners généraux.
Aucun template, skeleton, audit Python ou contrat `docs/validation/` n'est créé par cette tranche.
## Réévaluation initiale de `610-ANDROID.md`
Le profil courant contient déjà une part importante des contrats démontrés par Games : structure conditionnelle, matrice AGP/Gradle/JDK, niveaux SDK séparés, version Android, configuration locale, signing, modules, dépendances, ABI conditionnelles, niveaux de tests, validation proportionnée, manifests/resources et artefacts APK/AAB.

84
docs/rules/610-ANDROID.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/rules/610-ANDROID.md -->
<!-- version: 3 -->
<!-- version: 4 -->
# Profil Android
@@ -15,7 +15,7 @@ Les profils Rust/JNI et Tauri ne sont pas définis ici. Ils constituent des comp
## Structure du projet
Pour un dépôt exclusivement Android, les conventions Android normales restent prioritaires et la racine du dépôt MAY être directement le projet Gradle.
Pour un dépôt exclusivement Android, les conventions Android normales restent prioritaires et la racine du dépôt MAY être directement le projet de build Android.
Dans un dépôt multi-plateforme où une zone Android distincte est nécessaire, PGR SHOULD utiliser la racine :
@@ -33,23 +33,25 @@ project/
├── crates/
├── Web/
└── Android/
├── settings.gradle
├── build.gradle
├── settings.gradle(.kts)
├── build.gradle(.kts)
├── gradle.properties
├── gradlew
├── gradlew.bat
└── gradle/
└── <module>/
```
Cet exemple décrit une frontière de plateforme, pas une liste obligatoire de fichiers Gradle. Wrapper, version catalog, plugins de convention, modules et autres éléments de build restent gouvernés par la composition réellement choisie et par [`522-GRADLE.md`](522-GRADLE.md).
Les noms et fichiers exacts restent soumis au projet Android réellement utilisé ; PGR ne crée pas de niveau `Android/` artificiel dans un dépôt qui est déjà exclusivement Android.
## Langage applicatif et logique de build
Java est le langage applicatif Android par défaut du profil PGR lorsqu'aucune API, framework ou contrainte réelle n'impose un autre choix.
Android ne sélectionne pas à lui seul le langage applicatif du projet. Les profils langage s'appliquent uniquement aux langages réellement présents.
Kotlin MAY être utilisé lorsqu'une API, un framework ou une intégration l'exige réellement.
Lorsqu'un projet Android contient du Java, [`520-JAVA.md`](520-JAVA.md) possède les règles Java correspondantes. La présence d'AGP, d'un JDK de build ou d'un script Gradle ne suffit pas à rendre le profil Java applicable au code produit.
Groovy DSL ou Kotlin DSL MAY être utilisés par Gradle comme langage de configuration. Leur présence dans le build ne transforme pas Kotlin ou Groovy en langage applicatif du projet.
Un autre langage applicatif MAY être utilisé lorsqu'il correspond à la stack réelle du projet. Le profil Android possède uniquement les contraintes imposées par la plateforme et ne transforme pas un choix de langage local en règle Android générale.
Groovy DSL ou Kotlin DSL MAY être utilisés par Gradle comme langage de configuration conformément à [`522-GRADLE.md`](522-GRADLE.md). Leur présence dans le build ne détermine pas le langage applicatif.
Les fichiers Gradle SHOULD rester aussi déclaratifs et courts que raisonnablement possible. Une logique de build importante SHOULD être possédée par une abstraction ou un plugin identifiable plutôt que devenir du code produit caché dans un script Gradle.
@@ -57,7 +59,7 @@ Les annotations fonctionnelles Android ou de frameworks restent autorisées lors
## Matrice AGP / Gradle / JDK
Un projet Android MUST exprimer une chaîne de build compatible.
Un projet Android qui utilise AGP MUST exprimer une chaîne de build compatible.
La matrice conceptuelle est :
@@ -66,9 +68,11 @@ Android Gradle Plugin
↕
Gradle
↕
JDK LTS
JDK de build
```
La version AGP retenue peut également contraindre les niveaux Android SDK supportés par la chaîne de build. Cette compatibilité appartient au scope Android ; les règles Gradle générales restent possédées par [`522-GRADLE.md`](522-GRADLE.md).
PGR MUST NOT imposer globalement une version Gradle, AGP ou JDK uniquement parce qu'elle est utilisée par un autre projet Android.
La contrainte applicable peut être :
@@ -80,27 +84,47 @@ version exacte / pin
latest compatible
```
Le projet choisit la forme la moins restrictive qui reste réellement compatible avec sa stack.
Le projet choisit la forme la moins restrictive qui reste réellement compatible avec sa stack et effectivement vérifiable.
Le JDK suit le profil Java : dernière LTS compatible par défaut, LTS plus ancienne lorsqu'une contrainte Android ou de framework l'impose, non-LTS uniquement par exception justifiée.
Le JDK utilisé pour exécuter Gradle/AGP est une contrainte de build Android même lorsqu'aucun code source Java n'existe. Lorsqu'un projet contient du Java, le niveau Java du code source et du bytecode reste un contrat distinct possédé par [`520-JAVA.md`](520-JAVA.md).
Lorsque le Gradle Wrapper est retenu, ses fichiers requis sont versionnés et sa version doit satisfaire la matrice réelle AGP/Gradle/JDK.
PGR MUST NOT confondre :
```text
JDK qui exécute Gradle / AGP
≠
niveau Java du code applicatif
```
Le choix Wrapper ou Gradle système, ainsi que la manière de vérifier la contrainte Gradle, restent possédés par [`522-GRADLE.md`](522-GRADLE.md). Une matrice Android plus étroite MAY raffiner cette contrainte dans le seul scope Android.
## `compileSdk`, `targetSdk` et `minSdk`
Ces trois valeurs représentent des contrats différents.
`compileSdk` définit l'API Android utilisée pour compiler. Il MAY être récent afin de permettre l'usage des APIs et outils actuels.
`compileSdk` définit le niveau d'API Android disponible lors de la compilation. Il doit être compatible avec la version AGP réellement utilisée et MAY évoluer sans entraîner mécaniquement une hausse de `targetSdk` ou `minSdk`.
`targetSdk` déclare le niveau de comportement Android pour lequel l'application a été adaptée. Il MUST respecter les exigences applicables au canal de distribution réellement visé.
`targetSdk` déclare le niveau Android pour lequel l'application a été adaptée et testée du point de vue des comportements de plateforme. Il MUST respecter les exigences applicables au canal de distribution réellement visé.
`minSdk` définit la plus ancienne version Android que le produit promet de pouvoir installer et exécuter.
`minSdk` définit le plus ancien niveau d'API Android que le produit choisit réellement de supporter. Il participe notamment à l'éligibilité d'installation sur les appareils plus anciens.
PGR MUST NOT déduire une hausse de `minSdk` d'une hausse de `compileSdk` ou `targetSdk`.
`minSdk` SHOULD rester aussi bas que raisonnablement supportable tant que cela ne compromet pas une capacité nécessaire, une dépendance imposée, la sécurité ou une maintenance raisonnable.
Le choix de `minSdk` MUST être justifié par le contrat produit et ses contraintes réelles : population visée, capacités nécessaires, dépendances, sécurité, coût de maintenance et preuves de compatibilité. PGR ne privilégie ni le niveau le plus bas possible ni une hausse de confort sans justification.
Une hausse de `minSdk` est un changement de compatibilité utilisateur et MUST être explicitement justifiée.
Une hausse de `minSdk` retire explicitement des appareils auparavant éligibles ; elle constitue donc un changement de compatibilité utilisateur et MUST être traitée comme tel.
## Identité applicative et namespace
Pour un module application Android, `applicationId` et `namespace` sont deux contrats distincts.
`applicationId` identifie l'application installée et distribuée. Pour une application déjà publiée, le modifier ne constitue pas un simple renommage de code : il crée une identité applicative différente du point de vue de la plateforme et des canaux de distribution.
`namespace` possède l'espace de noms utilisé par le code et les ressources générées du module. Il MAY évoluer indépendamment de `applicationId` lorsque le projet a une raison réelle de dissocier identité distribuée et organisation du code.
PGR SHOULD conserver `namespace` et `applicationId` alignés lorsque cela suffit, mais MUST NOT les confondre ni dériver implicitement l'identité distribuée d'un renommage de namespace. Toute divergence ou modification d'`applicationId` doit être explicite dans la configuration Android concernée.
Les valeurs concrètes telles que `com.example.product` appartiennent au projet ; PGR n'impose aucun domaine ou préfixe universel.
## `VERSION`, `versionName` et `versionCode`
@@ -135,15 +159,15 @@ lorsqu'un projet ou skeleton réel fournit des fichiers à contrôler. Cet audit
## Configuration locale
`local.properties` est un fichier local Android typique et SHOULD rester hors Git lorsqu'il contient des chemins machine tels que l'emplacement du SDK.
`local.properties` appartient à l'environnement local du build Android/AGP, notamment pour des chemins machine tels que l'emplacement du SDK. Il SHOULD rester hors Git.
PGR MUST NOT utiliser `local.properties` comme source normative de configuration partagée du projet.
PGR MUST NOT utiliser `local.properties` comme source normative de configuration partagée ni comme fourre-tout pour des propriétés locales propres au produit. La documentation Android réserve ce fichier aux propriétés locales comprises par la toolchain Android ; une propriété locale spécifique au projet doit utiliser un mécanisme séparé et explicitement possédé.
Si l'outil ou l'IDE régénère intégralement ce fichier, aucun fichier exemple n'est nécessaire.
Les propriétés Gradle partagées, portables et non secrètes restent gouvernées par [`522-GRADLE.md`](522-GRADLE.md). Les chemins machine, credentials, secrets et overrides développeur restent locaux, via variables d'environnement, propriétés utilisateur ou fichier explicitement ignoré selon le besoin réel.
Lorsqu'une propriété locale obligatoire n'est pas automatiquement reproductible, un template MAY être fourni conformément aux règles générales PGR.
Si l'outil ou l'IDE régénère intégralement un état local, aucun fichier exemple n'est nécessaire. Lorsqu'une valeur locale obligatoire n'est pas automatiquement reproductible, un template MAY être fourni conformément aux règles générales PGR.
La même politique s'applique aux fichiers locaux analogues tels que `keystore.properties`, `user.properties` ou des variantes `*.local.properties` lorsqu'ils contiennent des valeurs propres à la machine ou à l'utilisateur.
Un fichier local tel que `keystore.properties` ou une variante `*.local.properties` MAY exister lorsqu'il possède une responsabilité claire, mais il MUST rester hors Git lorsqu'il contient des secrets ou valeurs propres à la machine.
## Signing et secrets
@@ -152,7 +176,7 @@ L'interdiction générale de versionner ou distribuer des secrets reste posséd
Dans le scope Android, les éléments suivants sont notamment des secrets ou artefacts privés soumis à cette interdiction :
```text
release keystore
release / upload keystore
private signing key
passwords
credentials
@@ -168,7 +192,9 @@ RELEASE_KEY_ALIAS
mais MUST NOT contenir leurs valeurs privées.
Le debug keystore généré automatiquement est local.
Le debug keystore généré par les outils Android est un état local de développement et ne doit pas être promu comme identité de signing de release.
Les clés de release ou d'upload appartiennent à une frontière de sécurité durable de l'application publiée. Leur stockage, sauvegarde, rotation ou délégation au canal de distribution doit être décidé explicitement par le projet sans introduire la matière secrète dans Git.
Le signing de release ne doit pas être requis pour une validation ordinaire de développement sauf lorsque la tranche valide précisément la distribution ou la signature finale.
@@ -274,10 +300,12 @@ Les commandes exactes appartiennent à la matrice du projet ou du skeleton qui p
## Manifest et ressources
`AndroidManifest.xml` MUST déclarer uniquement les permissions et capabilities réellement nécessaires.
`AndroidManifest.xml` MUST déclarer uniquement les composants, permissions et capabilities de plateforme réellement nécessaires au module.
Une permission sensible ne doit pas être ajoutée « au cas où ». Son introduction constitue un changement significatif qui doit être visible dans le delta et, lorsque pertinent, dans la documentation de release.
`applicationId` et `namespace` restent possédés par la configuration Android du module ; PGR SHOULD éviter de créer des sources de vérité concurrentes ou des copies divergentes de ces identités dans des fichiers séparés.
`src/main/res/` reste la source canonique des ressources Android d'un module standard.
Dans un projet multi-plateforme, des assets réellement partagés MAY vivre dans un owner commun hors d'Android si leur consommation est définie clairement.