Contribuindo para o azk

Antes de tudo, você é incrível! Obrigado por contribuir com o azk!

Existem diversas maneiras de ajudar, e todas elas são bem-vindas:

  1. Abrir issues
  2. Comentar em issues abertos
  3. Fazer PRs
  4. Testar PRs
  5. Escrever testes
  6. Escrever documentação
  7. Arrumar erros de escrita

Abaixo, você pode encontrar algumas seções com informações mais detalhadas. Recomendamos também dar uma olhada no próprio guia do GitHub "Contributing to Open Source on GitHub".

Seções

  1. Dúvidas e suporte
  2. Abrir issues
  3. Dicas e orientações
    1. Estrutura das pastas
    2. Detalhes de implementação
    3. Qualidade e estilo do código
    4. Ferramenta de tarefas - Gulp
  4. Pull Requests
    1. JavaScript e Node.js
    2. Contribuir com código
    3. Organização de branches
    4. Convenções
      1. Branches
      2. Mensagens de commit
    5. Testes
      1. Testes de integração
      2. Filtrar testes
    6. Adicionando ou atualizando dependências
    7. Abrir Pull Requests
      1. Formato do Pull Request

Dúvidas e suporte

A documentação para o azk, que você está lendo agora, é a principal fonte de informações sobre o projeto. Temos também um bate-papo no Gitter em Inglês e Português que pode ser útil para fazer perguntas em tempo real, diretamente para a nossa equipe de desenvolvedores e outros membros da comunidade.

Abrir issues

Os erros são comunicados através da criação de novas issues no GitHub. Elas nos ajudam a corrigir erros que possam ter escapado no nosso processo de teste ou release.

Antes de criar novas issues por favor, certifique-se de que não há outras similares já criadas. Se você encontrar alguma que seja semelhante, adicione um comentário :+1: nela, e também qualquer informação adicional que nos ajude a reproduzir o erro como: OS, versão do azk, comandos utilizados, Azkfile.js, etc.

Idealmente, uma issue deve conter uma descrição básica do seu sistema, uma descrição do erro, e instruções sobre como reproduzi-lo. Nós encorajamos você a abrir um problema mesmo se você não consiga se lembrar dos passos para realiza-lo novamente, ou reproduzi-lo (caso ele seja intermitente).

Um exemplo de um bom formato para uma issue:

Toda a comunicação dentro do nosso repositório é feita em inglês, mas fique a vontade para escrever em português também.

Inglês:

Description of the problem:

`OS`:
`azk version`:

Environment details (VirtualBox, DigitalOcean, etc.):

Steps to Reproduce:
1.
2.
3.

Actual Results:

Expected Results:

Additional info:

Português

Descrição do problema:

`OS`:
`azk version`:

Detalhes do ambiente (VirtualBox, DigitalOcean, etc.):

Passos para reproduzir o erro:
1.
2.
3.

Resultado atual:

Resultado esperado:

Informação adicional:

Dicas e orientações

Estrutura das pastas

  • /bin: binários do azk: adocker e azk.
  • /docs: documentação no formato Gitbook.
  • /shared:
    • Azkfile.js: Azkfile.js do próprio azk. Configura o dns e o load balancer.
    • locales/en-US.js: Todas as mensagens e textos mostrados no cli.
    • templates/Azkfile.mustache.js: Template de um Azkfile.js escrito em mustache (usando Handlebars).
  • /spec: Todos os testes do azk.
  • /src: Código fonte.
  • /lib: Código fonte compilado.
  • .dependencies: Arquivo onde as versões das dependências são definidas.
  • .jscsrc: Configura o padrão de estilo de código.
  • .jshintrc: Configura a validação da sintaxe do JavaScript.
  • Makefile: Tarefas de empacotamento.
  • npm-shrinkwrap.json: Especifica as versões das dependências listadas no package.json.
  • package.json: Todas as dependências do azk.
  • gulpfile.js: Tarefas do gulp. Para mais informações, execute azk nvm gulp help.

Detalhes de implementação

O código do azk é escrito em Node.js. Ele usa vários recursos de ES6 que ainda não estão disponíveis em uma versão estável, e por isso o código passa por uma etapa de compilação para que ele possa ser interpretado corretamente pela versão atual do Node.js. Nós usamos o babeljs para isso, que oferece muitos recursos de ES6 (ver: babeljs compat-table). Durante o processo de "transpilation", nós sempre configuramos o source-map para "on". Isso permite que o código gerado mostre os erros que apontando corretamente para o código-fonte original.

Uma coisa que você vai notar logo que começar a mergulhar no código do azk é o uso de promises com generators. Isso permite que o nosso código assíncrono torne-se mais semelhante ao código síncrono, tornando-o mais fácil de ler. Usamos a biblioteca de promessas bluebird-generators que suporta generators.

Qualidade e estilo do código

Nós utilizamos o .jshintrc e o .jscsrc configurados com o esnext ligado, ou seja, com várias features do ES6. Veja os links abaixo para descobrir a melhor forma de configurar seu editor com essas ferramentas de qualidade de código:

Além disso, nós utilizamos o arquivo .editorconfig para manter a consistência do estilo de código, independente da IDE ou editor que qualquer um esteja usando. Você pode ver mais informações sobre arquivos EditorConfig aqui, e também ver como o nosso está configurado aqui.

Ferramenta de tarefas - Gulp

Para o desenvolvimento do azk, usamos o gulp para coordenar as tarefas do dia-a-dia de desenvolvimento, tais como:

  • "Transpilar" arquivos es5 para es6 com babeljs;
  • Verificar a qualidade do código com jshint e jscs;
  • A execução de um comando "watch" para modificação dos arquivos e execução das tarefas acima automaticamente;

Você pode encontrar a lista completa de comandos disponíveis executando: azk nvm gulp help, mas a tarefa principal que você deve conhecer e usar durante o desenvolvimento é azk nvm gulp watch:test:lint.

Pull Requests

Antes de tudo, instale o azk a partir do código-fonte:

$ git clone https://github.com/azukiapp/azk.git
$ cd azk
$ make

Então adicione o caminho para o binário do azk a variável de ambiente PATH, ou crie um alias para ele.

Existem passos adicionais que você precisará seguir caso esteja realizando a instalação no Mac ou no Linux (por exemplo, realizar a instalação do libnss-resolver). Olhe essa página da documentação para instruções mais detalhadas.

JavaScript e Node.js

Como mencionado na seção "Detalhes de implementação", o azk é escrito em Node.js, e utiliza vários recursos do ES6. Uma coisa a notar é que, para ajudar no desenvolvimento e contribuir para o azk, você não precisa ter Node.js instalado em sua máquina.

O azk possui uma versão do Node.js, que é o mesmo que usamos para testá-lo e desenvolvê-lo, dentro da pasta "./lib/nvm". Ele já vem instalado e empacotado quando você baixa o azk através de um gerenciador de pacotes, ou ele também é instalado caso você baixe o projeto do GitHub e execute make para construir seu binário. Isso significa que nós podemos:

  1. Ter certeza de que o azk está sendo executado e usando uma versão do Node.js que testamos.
  2. Não exigir que o usuário possua o Node.js instalado em sua máquina, e caso ele esteja instalado, não afetar o ambiente de desenvolvimento de qualquer forma.

Durante o desenvolvimento, no caso de você querer usar comandos node, você pode executar:

$ azk nvm node [command]

# Ou

$ azk nvm npm [command]

Caso você queira instalar alguma dependência, o processo será algo como:

$ azk nvm npm install gulp

E então você poderá usar o módulo com:

$ azk nvm gulp

Contribuir com código

Todas as contribuições de código são bem-vindas, seja ela para consertar uma issue ou adicionar novas funcionalidades.

O fluxo de trabalho geral segue estes passos:

  • Abra uma issue / Encontre uma issue aberta / Sugerir uma feature através da nossa página de issues no GitHub
  • Discutir a issue/feature com nossa equipe de desenvolvedores e membros da comunidade
  • Pegar a issue/feature para você consertar/criar
  • Fork azk
  • Criar uma "feature branch" e começar a trabalhar
  • Sincronizar o seu trabalho com a branch master de tempos em tempos
  • Abrir um PR e iterar
  • PR aceito e merged!

Em comandos shell, isso será algo parecido com:

# Fork o repositório do azk
$ git clone https://github.com/your_username/azk.git
$ cd azk
$ git checkout -b feature/feature_name
# Faça mudanças nos arquivos
$ make
# Execute os testes
$ azk nvm npm test
$ git add .
$ git commit -m "[my new feature] Fixing some system tests"
$ git push
# Abra o PR da sua feature branch para a master branch do azk

Lembre-se de fazer um fork diretamente no GitHub. Todas as contribuições são feitas através de Pull Requests na branch master do repositório principal.

Organização de branches

  • master é a branch de desenvolvimento.

    A branch master é onde novas features são iniciadas, e onde elas serão "merged".

  • stable é a versão estável.

    A branch stable é a versão mais recente e estável do azk. É ela que utilizamos para construir os binários, disponíveis nos gerenciadores de pacotes.

Convenções

Branches

Ao criar uma branch na qual você irá trabalhar, lembre-se de nomeá-la como feature/feature_name.

Mensagens de commit

As mensagens de commit seguem uma convenção:

git commit -m '[YOUR_BRANCH_NAME] comment'

Isso nos ajuda ao consultar e filtrar o histórico do git no futuro, para ver de onde as mudanças vieram.

Testes

O azk utiliza o mocha como o framework de testes, e o gulp coordena as tarefas necessárias para o uso diário.

Para executar os testes do azk, o azk agent deve estar em execução:

$ azk agent start
...
azk: Agent has been successfully started.
$ azk nvm npm test

Testes de integração

Os testes de integração do azk são escritos utilizando bats, e podem ser encontrados dentro da pasta "specs/integration". Antes de rodar os testes você precisará instalar algumas dependências:

$ make dependencies

E então você poderá executá-los com:

$ azk nvm gulp integration

Note que para rodar os testes, é necessário que o azk agent esteja em execução.

Filtrar testes

Nós podemos filtrar os testes a serem executados por seções específicas, ou individualmente, com:

$ azk nvm gulp test --grep="Azk command init run"

Similar aos testes funcionais, você pode filtrar os testes de integração com:

$ azk nvm gulp integration --grep="force to replace a"

Adicionando ou atualizando dependências

Para ajudar a gerenciar as dependências do azk, nós utilizamos o npm shrinkwrap para realizar o "lock" das versões que usamos (mais informações sobre isso aqui). Por isso, se você precisar adicionar uma dependência ao azk, ou atualizar uma já existente, certifique-se de gerar o arquivo npm-shrinkwrap.json novamente.

Você pode encontrar mais informações sobre os comandos necessários para fazer isso aqui, mas deve ser simples como:

  1. Execute "npm install" no root do pacote para instalar as versões atuais de todas as dependências.
  2. Adicionar ou atualizar dependências. "npm install" cada pacote novo ou atualizado individualmente e depois atualizar o package.json. Note-se que eles devem ser explicitamente chamados para serem instalados: executando npm install sem argumentos irá somente reproduzir o shrinkwrap existente.
  3. Confirme que o pacote funciona como previsto com as novas dependências.
  4. Execute "npm shrinkwrap", "commit" o novo npm-shrinkwrap.json, e publique o pacote.

Abrir Pull Requests

Antes de abrir um Pull Request, certifique-se de que você:

  • Testou o binário do azk com suas alterações:
$ make
# Tenha certeza de que o azk sendo executado é o da pasta de desenvolvimento, não do package manager
$ azk nvm npm test
  • "Merge" de forma limpa com a branch master

Seu trabalho deve fazer o "merge" de forma limpa com a branch master. No caso de haver commits adicionais feito na branch master depois de você ter criado sua branch, faça um git rebase:

$ git remote add upstream https://github.com/azukiapp/azk.git
$ git fetch --all
$ git checkout master
$ git merge upstream/master
$ git checkout feature/your_feature_name
$ git rebase master

Caso você já tenha feito um push para seu repositório, após fazer um rebase será necessário fazer um git push -f.

  • Ter commits que são pequenas unidades lógicas de trabalho

Durante o desenvolvimento, você pode acabar com um grande número de commits que podem ter mensagens confusas, ou partes do trabalho que poderiam estar juntas. Uma coisa que você pode fazer é usar o git rebase -i para modificar seus commits anteriores. Essas mudanças podem variar de simplesmente certificar-se de que todas as mensagens seguem as convenções do repositório, quanto para juntar as mudanças feitas em diversos commits a um único.

$ git rebase -i HEAD~X
# X sendo o número de commits que você quer modificar

Caso você precise de ajuda para fazer qualquer uma das coisas acima, basta abrir um PR e nós vamos ajudá-lo através dele. :)

Formato do Pull Request

Ao abrir um pull request, você deve incluir as seguintes informações:

Toda a comunicação dentro do nosso repositório é feita em inglês, mas fique a vontade para escrever em português também.

Inglês

Issues that are closed by this PR (Use they keyword "closes", so the issues are closed automatically after the work is merged)

Description of the pull request:

How to test the PR:
1.
2.
3.

Additional info:

Português

Issues que são fechadas pelo PR (Use a palavra-chave "closes", para que as issues sejam fechadas automaticamente após o trabalho ser "merged")

Descrição do pull request:

Como testar o PR:
1.
2.
3.

Informação adicional: