Comprendre la structure du code de Gaia

Les branches de Gaia

Il y a plusieurs branches différentes qui organisent le code source de Gaia, et en fonction de la tâche que vous cherchez à accomplir (ou de l'appareil que vous avez), vous ne voudrez pas seulement charger, modifier et compiler la branche master. Vous trouverez ici, une rapide explication, des branches les plus couramment utilisées :

• master - La dernière branche de développement. Vous voudrez utiliser cette branche, si vous développez (ou corrigez des bugs) sur des nouvelles fonctionnalités, ou que vous voulez lancer la dernière version de Gaia sur votre téléphone ou votre émulateur.
• v2.1, v2.0, v1.4, etc ... - Représentent des versions figées de Gaia 2.1, 2.0, 1.4, etc ... Vous voudrez utiliser ces branches si vous corrigez un bug sur une version spécifique de Gaia, ou que vous voulez développer une application et vous assurer que celle-ci supporte bien une version spécifique de Gaia. Par exemple, vous pourriez utiliser Firefox OS Building Blocks pour réaliser des modifications, et vous assurer que votre agencement soit toujours optimal sur les différentes versions de Gaia.
• v1.3t - La version basse consommation en mémoire de Gaia, développée pour fonctionner sur des périphériques ayant peu de mémoire, comme le Tarako ou le Spice Fire One. Si vous désirez développer une application pour un périphérique semblable, c'est la branche sur laquelle vous devrez être.

La structure du code source de Gaia

La section qui suit présente les parties les plus importantes du code source de Gaia.

apps/

Ce répertoire contient chacune des applications principales de Gaia, celles affichées sur l'écran d'accueil - comme le calendrier ou l'appareil photo - ainsi que celles sous-jacentes - comme celle du système, celle de l'écran d'accueil, ou celle du clavier.

Les applications peuvent fonctionner de façon légèrement différente, mais ont toutes un certain nombre de points communs :

• index.html : le fichier principal de l'application
• manifest.webapp : le fichier de manifeste définissant l'application
• locales : les chaines de traduction pour l'application
• test : les tests unitaires et les tests d'intégration de l'application
• js, style : les scripts et les styles de l'application
• resources : les images, sons et autres ressources pour l'application

build/

Ce répertoire contient les scripts de construction (build).

dev_apps/

Ce répertoire contient les applications à inclure lors d'une construction faite sur mesure. Par exemple, vous pouvez ajouter des applications à cet emplacement pour produire des versions sur mesures qui contiennent ces applications.

keyboard/

Ce répertoire contient les dictionnaires et agencements des claviers en fonction des différentes langues.

locales/

Ce répertoire contient un fichier JSON, languages_all.json, qui définit les langues supportées dans Gaia. Pour plus d'informations sur la façon dont les applications sont localisées, lire l'article Comment localiser une application.

shared/

Ce répertoire contient diverses ressources utilisées par plusieurs applications. Les éléments les plus notables sont :

• gaia/shared/js : les bibliothèques JavaScript qui contiennent des fonctionnalités communes de base
• l10n.js : une bibliothèque de localisation qui permet de détecter la langue de l'appareil et de remplacer les chaînes de l'application par les chaînes trouvées dans les répertoires de locales des applications. Les chaînes à traduire doivent être placées dans des éléments HTML qui possèdent l'attribut data-l10n-id.
• gaia/shared/locales : Les ressources traduites pour les différentes locales.
• gaia/shared/resources : Les fichiers média communs tels que les icônes, les sonneries, les sons à utiliser pour l'alarme, etc.
• gaia/shared/style : les feuilles de style et les autres ressources de mise en forme pour les blocs de construction communs comme les boutons, barres de progressions, barres d'outils, onglets, etc.
• gaia/shared/style_unstable : ressources de mise en forme instables ou expérimentales.
• gaia/shared/test : le code JavaScript qui définit les tests d'intégration et les tests unitaires.

tools/

Ce répertoire contient les utilitaires nécessaires pour les scripts de construction (build) et les tests.

Les conventions de style utilisées pour le code de Gaia

Gaia suit les règles de style de Google pour le JavaScript (en anglais).

Informations générales sur les règles de code :

• Pratiques générales
• Pratiques pour JavaScript
• Conventions de nommage et de formattage

Règles spécifiques

1. Assurez-vous que vos fichiers HTML soient déclarés avec <!DOCTYPE html> (autrement dit, qu'ils soient des documents HTML5). Si vous n'utilisez pas cette information, les versions Internet Explorer 9 et supérieures chargeront le site/application en mode de compatibilité.
2. Incluez l'instruction "use strict"; (telle quelle, avec les doubles quotes) dans vos fichiers JavaScript afin qu'ils utilisent le mode strict.
3. Utilisez deux espaces pour l'indentation et non pas des tabulations.
4. Veuillez utilisez des sauts de ligne pour séparer les fragments logiques du code !
5. Les noms de fichiers composés de plusieurs termes doivent utiliser les tirets bas comme ceci mon_fichier_avec_plusieurs_mot.js.
6. Utilisez des quotes simples pour les chaînes de caractères (plutôt que des doubles quotes).
7. Utilisez des structures conditionnelles développées :

   Incorrect
   if (expression) faireQuelqueChose();
   
   Correct
   if (expression) {
     faireQuelqueChose();
   }

8. Si vous travaillez sur l'application System, vérifiez la liste de conseils spécifiques.

Vérification du style de code à chaque commit

Gaia utilise JSHint pour vérifier le style de code JavaScript utilisé et ce avant chaque commit (via un « crochet » (hook en anglais) git). Une fois que vous avez soumis votre pull request sur le dépôt de Gaia. Le serveur Travis (l'intégration continue pour Github) lancera ce « linter » pour vérifier à nouveau que le style est correct.

Le script de pre-commit est présent dans gaia/tools/pre-commit et devrait être copié dans le répertoire .git/hooks du projet une fois que la commande make a été lancée.

Lancer le linting manuellement avec Gaia

Avant de soumettre un correctif, il est conseillé de lancer JSHint manuellement en local afin de vérifier que vous n'avez pas d'erreurs de style dans votre code.

Pour plus de détails sur JSHint dans Gaia, vous pouvez regarder le contenu du répertoire gaia/build/jshint. Gaia fournit un script de construction que vous pouvez utiliser :

$ make lint

pour lancer automatiquement les tests de gjslint et de JSHint. Vous pouvez également lancer uniquement :

$ make hint

pour ne lancer que les vérifications effectuées par JSHint.

$ make eslint

pour lancer uniquement la vérification de style eslint.

npm install jshint -g
jshint mon_fichier.js