Como contribuir para o código

Você está prestes a contribuir para o Nette Framework e precisa se orientar sobre as regras e procedimentos? Este guia para iniciantes mostrará passo a passo como contribuir eficazmente para o código, trabalhar com repositórios e implementar alterações.

Procedimento

Para contribuir para o código, é essencial ter uma conta no GitHub e estar familiarizado com os fundamentos do trabalho com o sistema de controle de versão Git. Se você não domina o trabalho com o Git, pode consultar o guia git – the simple guide e, opcionalmente, usar um dos muitos clientes gráficos.

Preparação do ambiente e do repositório

  1. No GitHub, crie um fork do repositório do pacote que você pretende modificar.
  2. Clone este repositório para o seu computador.
  3. Instale as dependências, incluindo o Nette Tester, utilizando o comando composer install.
  4. Verifique se os testes funcionam executando composer tester.
  5. Crie um novo branch baseado na última versão lançada.

Implementação das suas próprias alterações

Agora você pode fazer as suas próprias modificações no código:

  1. Implemente as alterações desejadas e não se esqueça dos testes.
  2. Certifique-se de que os testes são executados com sucesso, utilizando composer tester.
  3. Verifique se o código cumpre os padrões de codificação.
  4. Salve (commit) as alterações com uma descrição neste formato.

Você pode criar vários commits, um para cada passo lógico. Cada commit deve ser significativo por si só.

Envio das alterações

Assim que estiver satisfeito com as alterações, pode enviá-las:

  1. Envie (push) as alterações para o GitHub no seu fork.
  2. A partir daí, envie-as para o repositório Nette criando um pull request (PR).
  3. Forneça informações suficientes na descrição.

Incorporação de comentários

Os seus commits serão agora vistos por outros. É comum receber comentários com sugestões:

  1. Acompanhe as modificações propostas.
  2. Incorpore-as como novos commits ou faça rebase com os anteriores.
  3. Envie novamente os commits para o GitHub e eles aparecerão automaticamente no pull request.

Nunca crie um novo pull request para modificar um existente.

Documentação

Se você alterou a funcionalidade ou adicionou uma nova, não se esqueça de a adicionar também à documentação.

Novo branch

Se possível, faça as alterações em relação à última versão lançada, ou seja, a última tag no branch correspondente. Para a tag v3.2.1, crie um branch com este comando:

git checkout -b new_branch_name v3.2.1

Padrões de Codificação

O seu código deve cumprir os padrões de codificação utilizados no Nette Framework. Existe uma ferramenta automática disponível para verificar e corrigir o código. Pode ser instalada via Composer globalmente na pasta da sua escolha:

composer create-project nette/coding-standard /path/to/nette-coding-standard

Agora você deve conseguir executar a ferramenta no terminal. O primeiro comando verifica e o segundo também corrige o código nas pastas src e tests no diretório atual:

/path/to/nette-coding-standard/ecs check
/path/to/nette-coding-standard/ecs check --fix

Descrição do commit

No Nette, os assuntos dos commits têm o formato: Presenter: fixed AJAX detection [Closes #69]

  • área seguida por dois pontos
  • propósito do commit no tempo passado; se possível, comece com uma palavra como: “added” (nova funcionalidade adicionada), “fixed” (correção), “refactored” (alteração no código sem alteração de comportamento), “changed”, “removed”
  • se o commit quebrar a compatibilidade retroativa, adicione “BC break”
  • possível vínculo com o gestor de issues como (#123) ou [Closes #69]
  • após o assunto, pode seguir uma linha em branco e depois uma descrição mais detalhada, incluindo, por exemplo, links para o fórum

Descrição do pull request

Ao criar um pull request, a interface do GitHub permitirá que você insira um título e uma descrição. Forneça um título conciso e, na descrição, forneça o máximo de informações possível sobre os motivos da sua alteração.

Também será exibido um cabeçalho onde você especifica se é uma nova funcionalidade ou correção de erro e se pode haver quebra de compatibilidade retroativa (BC break). Se houver um problema relacionado (issue), crie um link para ele para que seja fechado após a aprovação do pull request.

- bug fix / new feature?  <!-- #números das issues, se houver -->
- BC break? yes/no
- doc PR: nette/docs#?    <!-- altamente bem-vindo, veja https://nette.org/en/writing -->
  1. Documentação
  2. Torne-se um contribuidor do Nette
  3. Como contribuir para o código