Entendendo o codebase do Gaia

Antes de começar a fazer suas próprias modificações no codebase do Gaia, você deve entender os conceitos básicos de sua estrutura, e quais as convenções de código são utilizadas. Esse artigo cobre ambos os pontos.

Estrutura do codebase do Gaia

A seção a seguir descreve partes mais importantes do codebase Gaia.

apps/

Esse diretório contem todos os aplicativos principais do Gaia que aparecem na tela inicial — como o calendário e câmera — e os aplicativos básicos — como system, tela incial e teclado.

Os aplicativos funcionam de maneiras ligeiramente diferentes, mas todos têm uma série de características comuns, tais como:

index.html: o arquivo central do aplicativo
manifest.webapp: o arquivo de manifesto que define o aplicativo
locales: as strings de localização do aplicativo
test: testes unitários e integrados próprios do aplicativo
js, style: scripts e estilos do aplicativo
resources: imagens, sons e outros arquivos

Nota: Você pode encontrar mais informações sobre como os aplicativos realmente funcionam no guia de aplicativos Gaia.

build/

Esse diretório contem os scripts de compilação.

dev_apps/

Esse diretório contem outros aplicativos que são incluídos por customização. Por exemplo, você quiser incluir aplicativos na sua própria compilação, devem ser armazenados nesse diretório.

Nota: Para mais informações sobre customização do Gaia, leia nosso Guia de customização.

keyboard/

Esse diretório contem dicionários e layouts para diferentes idiomas.

locales/

Esse diretório contém o arquivo JSON languages_all.json, que define os idiomas suportados no Gaia. Para mais informações sobre como os aplicativos são localizados, leia Primeiros passos com a localização de aplicativos.

shared/

Esse diretório contém diversos recursos que muitos aplicativos podem usar, os mais comuns são:

gaia/shared/js: bibliotecas JavaScript que executam funções comuns
l10n.js: Biblioteca de localização que detecta o idioma do seu dispositivo a partir do local, e substitui as strings "localizáveis" do seu aplicativo com as strings referentes ao idioma armazenadas nos diretórios de localização. As strings "localizáveis" são identificadas nos elementos que possuem atributos data-l10n-id.
gaia/shared/locales: Recursos localizados para diferentes idiomas.
gaia/shared/resources: Itens comuns como ícones, sons de toque do telefone e alarmes.
gaia/shared/style: páginas de estilos e outros recursos como botões, barras de ferramentas, tabs, etc.
gaia/shared/style_unstable: recursos instáveis ou experimentais.
gaia/shared/test: JavaScript para definir os testes unitários e integrados.

tools/

Esse diretório contém ferramentas para scripts de compilação e testes.

Estilo de codificação Gaia

O Gaia segue o estilo de codificação em JavaScript do Google.

Informações gerais:

Estilo de codificação: Práticas gerais
Estilo de codificação: Práticas de JavaScript
Estilo de codificação: Nomeando e formatando o código

Regras específicas

Certifique-se que os arquivos HTML possuem a declaração <!DOCTYPE html> (ou seja, documentos HTML5). Se não fizer a declaração o Internet Explorer 9 e anteriores irão carregá-lo no modo de compatibilidade..
Inclua o comando "use strict" (exatamente como descrito, incluindo as aspas) no início dos arquivos JavaScript para colocá-los em strict mode.
Sempre utilize dois espaços para identação ao invés de tabulação.
Por favor use quebras de linha para separar blocos lógicos do código!
Ao criar nomes de arquivos com mais de uma palavra use o caracter "sublinha" para separar as palavras, por exemplo: like_this.js.
Use plics (') ao invés de aspas (") para strings.

Use estruturas expandidas:

Bad
if (expression) doSomething();

Correct
if (expression) {
  doSomething();
}

Se você estiver trabalhando no aplicativo System, verifique esse guia.

Verificação do estilo de codificação "por commit"

Gaia usa jshint para verificar automaticamente estilos JS antes de cada commit. Uma vez que você submete um Pull Request ao repositório Gaia, o servidor Trevis (Github Continuous Integration) executará essa verificação para indicar se todos os estilos estão corretos.

O script de precommit está em gaia/tools/pre-commit e será copiado para o diretório do projet .git/hooks uma vez que o comando make é executado.

Nota: Nós estamos acostumados a usar gjslint para verificar os estilos de codificação, mas já está obsoleta e o uso do jshing é mais rigoroso e produz resultados melhores. Estamos usando JSHint desde o Firefox 1.4 e o gjslint somente é recomendado para o legado que não foi migrado para o JSHint.

Executando verificações manuais via Gaia

Antes de submeter uma correção, nós recomendamos que você execute JSHint manualmente para verificar algum erro de estilo.

Você deve olhar no diretório gaia/build/jshint para maiores detalhes sobre o jshint no Gaia. É fornecido um script para você:

$ make lint

para executar automaticamente os verificadores de estilo gjslint e jshint. Ou voc&e pode executar:

$ make hint

para executar somente o verificador de estilo jshint.

Nota: Se você quiser instalar o jshint sem usar o Gaia, use os seguintes comandos:

npm install jshint -g
jshint myfile.js