pgr/docs/rules/522-GRADLE.md

<!-- file: docs/rules/522-GRADLE.md -->
<!-- version: 1 -->

# Profil Gradle

## Rôle

Ce document possède les règles réutilisables propres au build tool Gradle.

Il complète [`500-LANGUAGES.md`](500-LANGUAGES.md) et, lorsqu'il construit du code Java, [`520-JAVA.md`](520-JAVA.md). Gradle n'est pas une règle implicite de tous les projets Java : ce profil s'applique uniquement lorsqu'un projet utilise réellement Gradle.

Android n'est pas défini ici. Toute contrainte propre à la plateforme Android appartient à [`610-ANDROID.md`](610-ANDROID.md) ou à un owner spécialisé et MAY raffiner localement le présent profil.

## Ownership du build

Un projet Gradle SHOULD centraliser la configuration commune lorsqu'elle est réellement partagée, sans déplacer au root une responsabilité qui appartient à un module particulier.

Selon le DSL retenu, les propriétaires naturels sont typiquement :

```text
settings.gradle / settings.gradle.kts
    -> composition du build et inclusion des projets
    -> politique de résolution des plugins/dépendances lorsqu'elle est réellement globale
    -> contraintes de bootstrap ou de version Gradle lorsqu'elles doivent s'appliquer avant la configuration des projets

build.gradle / build.gradle.kts root
    -> plugins, versions ou conventions réellement partagés
    -> configuration transverse qui ne doit pas être recopiée dans chaque sous-projet

build.gradle / build.gradle.kts de module
    -> plugins, dépendances, sources, tâches et paramètres propres au module

gradle.properties partagé
    -> propriétés portables, non secrètes et réellement communes au build
```

Cette répartition décrit des responsabilités, pas un layout obligatoire. Un build simple MAY légitimement porter moins de fichiers, et une logique transverse devenue importante MAY être extraite dans un script, build logic ou plugin clairement possédé plutôt que dupliquée.

Les sous-projets SHOULD NOT recopier sans nécessité :

- la compatibilité de langage lorsqu'elle est commune ;
- les repositories ;
- les versions de plugins ;
- les contraintes de dépendances ;
- les configurations de tests communes.

Les chemins machine, credentials, secrets et overrides propres à un développeur MUST NOT être introduits dans un `gradle.properties` partagé. Ils doivent utiliser un mécanisme local approprié, par exemple propriétés utilisateur Gradle, variables d'environnement ou fichier local explicitement ignoré lorsque la toolchain en possède un.

Un version catalog tel que `gradle/libs.versions.toml` MAY être utilisé lorsque la taille du projet le justifie. PGR MUST NOT l'imposer pour un projet qui n'en tire aucun bénéfice réel.

## Gradle Wrapper et version de Gradle

La contrainte Gradle doit refléter la matrice réellement supportée par le projet :

```text
minimum seulement
range min..max
version exacte/pinnée
latest compatible
```

Le projet MUST choisir la forme la moins restrictive qui prouve réellement sa compatibilité.

Un Gradle Wrapper SHOULD être versionné lorsqu'il apporte une reproductibilité utile pour la distribution, la CI ou l'onboarding. Son absence dans un corpus particulier ne constitue pas une règle générale.

Un projet contrôlé MAY utiliser un Gradle système si sa contrainte de compatibilité est **effectivement vérifiée** par le build ou par une gate exécutée par le projet/CI. Une version seulement écrite dans la documentation sans contrôle exécutable n'est pas une preuve suffisante de compatibilité.

La vérification peut être portée par `settings.gradle(.kts)`, par une logique de bootstrap ou par une gate dédiée adaptée au projet. PGR n'impose pas l'API Gradle exacte utilisée pour cette vérification.

Une plateforme ou un framework plus spécifique MAY imposer une contrainte plus étroite. Cette contrainte ne se propage jamais implicitement aux autres projets Gradle.

## DSL Gradle

PGR ne transforme pas une préférence de langage applicatif en interdiction du DSL de build.

Groovy DSL et Kotlin DSL sont tous deux reconnus. Un projet SHOULD retenir un DSL canonique et éviter de les mélanger arbitrairement.

Le code applicatif Java reste Java par défaut lorsque rien n'impose Kotlin/Groovy. Les scripts Gradle SHOULD rester aussi déclaratifs et courts que raisonnablement possible.

Une logique de build devenue importante SHOULD être déplacée vers une abstraction ou un plugin clairement possédé plutôt que grossir indéfiniment les scripts root.

## Validation Gradle

Les tâches ciblées sont préférées pendant le développement :

```bash
./gradlew :<module>:test
```

ou, lorsqu'un Gradle système est explicitement retenu :

```bash
gradle :<module>:test
```

Les tâches globales `check`, `build`, `assemble` ou de packaging complet SHOULD être sélectionnées lorsqu'elles correspondent réellement au scope, typiquement lors d'un changement transverse ou dans les phases de stabilisation/release.

`gradle clean` est une opération de maintenance et MUST NOT être utilisé comme précondition automatique à chaque build.

Lorsqu'un projet Gradle construit du Java, la déclaration du niveau source/bytecode reste gouvernée par [`520-JAVA.md`](520-JAVA.md). Gradle peut matérialiser ce contrat via ses mécanismes officiels, mais n'en devient pas le propriétaire normatif.

## Outputs, état local et Git

Les caches et sorties Gradle usuels sous `.gradle/` et `build/` ne sont pas versionnés.

Les métadonnées IDE spécifiques à une machine restent ignorées sauf exception explicitement partagée selon les règles générales du projet.

Les wrappers retenus sont une exception volontaire : ils peuvent être générés par l'outil, mais leurs fichiers nécessaires au bootstrap reproductible sont versionnés.

Les fichiers de configuration locale contenant chemins machine, credentials, secrets ou overrides développeur restent hors Git. Cette règle s'applique également aux propriétés Gradle locales : une propriété partagée doit rester portable et non secrète. Un template est ajouté uniquement lorsqu'un utilisateur doit réellement préparer une valeur non régénérée automatiquement.

## Validation et futurs audits PGR

Les catégories et l'autorité du gate restent possédées par [`400-VALIDATION.md`](400-VALIDATION.md).

PGR lui-même ne possède actuellement aucun projet Gradle exécutable à compiler. Aucune commande Gradle n'est donc ajoutée aux gates documentaires de PGR uniquement pour exercer le présent profil.

De même, aucun audit Gradle n'est créé uniquement pour matérialiser un outil. Lorsqu'un skeleton ou projet réel fournira un sujet stable, un audit monotâche MAY vérifier une propriété objectivement structurelle non mieux contrôlée par Gradle lui-même, par exemple une contrainte de version déclarée. Il reste read-only et ne lance jamais Gradle à la place de ses gates propres.