Chapters1 Reportando um Problema com o Rails
O Rails utiliza um projeto do Lighthouse para rastrear os problemas (primariamente bugs e contribuições de código novo). Se você encontrou um bug no Rails, este é o lugar para começar.
Bugs na versão mais recente do Rails provavelmente são os que obterão mais atenção. Além disso, a equipe do core Rails está sempre interessada em feedback daqueles que podem tirar tempo para testar o Rails edge (o código da versão do Rails que está atualmente em desenvolvimento). Mais tarde neste Guia você descobrirá como obter o Rails edge para testar.
1.1 Criando um Relatório de Bug
Se você encontrou um problema no Rails, pode começar adicionando um novo ticket no Lighthouse do Rails. No mínimo, seu ticket precisa de um título e um texto descritivo. Mas isto é somente o mínimo. Você deve incluir o maior número possível de informações relevantes. Você precisa no mínimo postar o exemplo de código que possua o problema. Melhor ainda é incluir um teste unitário que mostre como o comportamento esperado não está ocorrendo. Seu objetivo deve ser tornar fácil para você mesmo – e outras pessoas – replicar o bug e imaginar uma correção.
Você não deve atribuir o bug para um desenvolvedor específico do core (através da lista de seleção Who’s Responsible (quem é responsável)) a menos que saiba ao certo qual desenvolvedor irá trabalhar com qual patch. A equipe core revisa os problemas e atribui os desenvolvedores e milestones para eles periodicamente.
Você deve definir tags para seu problema. Utilize a tag “bug” para reportar um bug, e adicione a tag “patch” se você está anexando um patch. Tente encontrar algumas tags relevantes na lista de tags existentes (que aparecerão logo que você começar a digitar no textbox Choose some tags (escolha algumas tags)), antes de criar novas tags.
Então não levante suas esperanças. A menos que tenha um bug do tipo “Código Vermelho, Missão Crítica, O Mundo está Chegando ao Fim”, você está criando este ticket na esperança que outros com o mesmo problema possam colaborar com você para resolvê-lo. Não espere que o ticket automaticamente verá alguma atividade ou que outros pularão para corrigí-lo. Criar um ticket como este serve principalmente para ajudá-lo a iniciar no caminho de correção do problema e para os outros confirmarem com um comentário “Eu também estou tendo este problema”.
1.2 Tratamento Especial para Questões de Segurança
Se você encontrou uma vulnerabilidade de segurança no Rails, por favor não a reporte através de um ticket do Lighthouse. Os tickets do Lighthouse se tornam públicos logo que são registrados. Em vez disso, você deve usar o endereço de email security@rubyonrails.org dedicado para reportar quaisquer vulnerabilidades. Este alias é monitorado e a equipe core trabalhará com você para resolver de forma rápida e completamente tais vulnerabilidades.
1.3 E Sobre Solicitações de Funcionalidades?
Por favor não coloque tickets de “solicitação de funcionalidade” no Lighthouse. Se há uma nova funcionalidade que você quer ver adicionada ao Rails, você mesmo terá que escrevê-la – ou convencer alguém a associar-se com você para escrever o código. Posteriormente neste guia você encontrará instruções detalhadas para propor um patch para o Rails. Se você inserir um item da sua lista de desejos no Lighthouse sem código, pode aguardar que ele será marcado como “inválido” logo que for revisado.
2 Rodando o Conjunto de Testes do Rails
Para seguir em frente enviando bugs para ajudar a resolver problemas existentes ou contribuindo com seu próprio código no Rails, você deve ser capaz de executar o conjunto de testes do Rails. Nesta seção do guia você aprenderá como configurar os testes no seu computador.
2.1 Instale o git
O Rails utiliza o git para controle do código fonte. Você não será capaz de fazer nada sem o código fonte do Rails, e isto é um pré-requisito. A página inicial do git possui instruções de instalação. Se você está no OS X, utilize o instalador Git for OS X . Se você não conhece o git, existem uma variedade de recursos na rede que o ajudarão a aprender mais:
- Everyday Git lhe ensinará apenas o suficiente sobre o git para sobreviver.
- O PeepCode screencast sobre git ($9) é fácil de seguir.
- GitHub oferece links para uma variedade de recursos git.
2.2 Obtenha o Código Fonte do Rails
Não faça um fork do repositório principal do Rails. Em vez disso, você deve cloná-lo no seu computador. Navegue para o diretório onde você quer o código fonte (ele criará seu próprio subdiretório /rails) e execute:
git clone git://github.com/rails/rails.git
cd rails
2.3 Configure e Execute os Testes
Todos os testes do Rails devem passar com qualquer código que você enviar, senão você não terá chance do código ser aceito. Isto significa que você precisa ser capaz de executar os testes. Para os testes que usam o banco de dados, isto quer dizer criar os bancos necessários. Se você está usando MySQL:
mysql> create database activerecord_unittest;
mysql> create database activerecord_unittest2;
mysql> GRANT ALL PRIVILEGES ON activerecord_unittest.*
to 'rails'@'localhost';
mysql> GRANT ALL PRIVILEGES ON activerecord_unittest2.*
to 'rails'@'localhost';
Se você está utilizando outro banco de dados, verifique os arquivos em activerecord/test/connections no código fonte do Rails para informações padrão de conexão. Você pode editar estes arquivos se você for obrigado a fornecer credenciais diferentes na sua máquina, mas obviamente você não deve enviar tais modificações de volta para o Rails.
Agora se você voltar a raiz do código do Rails na sua máquina e executar rake sem nenhum parâmetro, deve ver passar cada teste em todos os componentes do Rails. Se você quiser executar todos os testes do ActiveRecord (ou apenas um) com outro adaptador de banco de dados, execute isto a partir do diretório activerecord:
rake test_sqlite3
rake test_sqlite3 TEST=test/cases/validations_test.rb
Você pode mudar sqlite3 por jdbcmysql, jdbcsqlite3, jdbcpostgresql, mysql ou postgresql. Verifique o arquivo activerecord/RUNNING_UNIT_TESTS para informações sobre como rodar mais testes específicos de banco de dados, ou o arquivo ci/ci_build.rb para ver o conjunto de testes que o servidor de integração contínua do Rails executa.
Se você está trabalhando com código do Active Record, deve se assegurar que os testes passem pelo menos para MySQL, PostgreSQL, SQLite 2, e SQLite 3. Diferenças sutis entre os vários adaptadores de bancos de dados Active Record tem estado por trás da rejeição de muitos patches que pareciam OK quando testados somente com o MySQL.
3 Ajudando a Resolver Problemas Existentesoplkk,l
Como próximo passo além de reportar problemas, você pode ajudar a equipe core a resolver problemas existentes. Se você checar a lista de tickets abertos no Lighthouse, encontrará centenas de problemas já exigindo atenção. O que você pode fazer por estes? Na verdade, bastante:
3.1 Verificar Relatórios de Bug
Para iniciar, simplesmente ajude a verificar relatórios de bug. Você pode reproduzir o problema reportado no seu computador? Se sim, pode adicionar um comentário ao ticket dizendo que você está vendo a mesma coisa.
Se algo é muito vago, você pode ajudar espremendo em algo específico? Talvez você possa fornecer informações adicionais para ajudar a reproduzir um bug, ou eliminar passos inúteis que não são necessários para ajudar a demonstrar o problema.
Se você encontrar um relatório de bug sem um teste, é muito útil contribuir com um teste de falha. Isto é também um grande modo de começar a explorar o código do Rails: olhar os arquivos de testes existentes irá ensinar-lhe como escrever mais testes para o Rails. Novos testes são melhor contribuídos na forma de um patch, como explicado posteriormente na seção “Contribuindo para o Código do Rails”.
Qualquer coisa que você possa fazer para tornar um relatório de bug mais sucinto ou fácil de reproduzir é uma ajuda às pessoas tentando escrever código para corrigir esses bugs – quer você mesmo acabe escrevendo o código ou não.
3.2 Testando Patches
Você também pode ajudar examinando patches que foram enviados para o Rails através do Lighthouse. Para aplicar as mudanças de alguém você primeiro precisa criar um branch no código fonte do Rails:
git checkout -b testing_branch
Então você pode aplicar o patch:
git am < their-patch-file.diff
Após aplicar um patch, teste-o! Aqui estão algumas coisas para pensar:
- O patch realmente funciona?
- Você está feliz com os testes? Pode seguir o que eles estão testando? Falta algum teste?
- A documentação ainda parece correta para você?
- Você gosta da implementação? Pode pensar em uma maneira mais agradável e rápida de implementar uma parte da mudança?
Uma vez que você estiver satisfeito que o patch contém uma boa mudança, comente no ticket do Lighthouse indicando sua aprovação. Seu comentário deve indicar que você gosta da mudança e o que você gosta nela. Algo como:
Eu gosto da maneira que você reestruturou esse código no generate_finder_sql, muito mais agradável. Os testes parecem bons também.
Se seu comentário simplesmente disser “+1”, então a probabilidade é que outros revisores não vão levá-lo muito a sério. Mostre que você tirou o tempo para revisar o patch. Uma vez que três pessoas o tenham aprovado, adicione a tag “verified” (verificado). Isto irá chamar a atenção de um membro da equipe core, que revisará as mudanças olhando para os mesmos tipos de coisas.
4 Contribuindo para a Documentação do Rails
Outra área onde você pode dar uma ajuda se ainda não está pronto para aventurar-se escrevendo código para o core do Rails é com a documentação do Rails. Você pode ajudar com os Rails Guides ou a documentação da API do Rails.
docrails é o branch de documentação para o Rails com uma política de commit aberta. Você pode simplesmente PM lifo no Github e pedir por direitos de commit. Mudanças na documentação feitas como parte do projeto docrails, são mescladas (merge) de volta ao código principal do Rails de tempos em tempos. Verifique o anúncio original para mais detalhes.
4.1 Os Rails Guides
Os Rails Guides são um conjunto de recursos online que são designados a tornar as pessoas produtivas com o Rails e a compreenderem como todas as peças se encaixam. Estes guias (incluindo este aqui!) são escritos como parte do projeto docrails. Se você tem uma idéia para um novo guia, ou melhoramentos para um guia existente, pode consultar a página de contribuição para instruções sobre como participar.
4.2 A Documentação da API do Rails
A documentação da API do Rails é gerada automaticamente a partir do código fonte do Rails via RDoc. Se você acha que alguma parte da documentação está incompleta, confusa, ou simplesmente errada, pode intervir e corrigí-la.
Para contribuir com uma atualização para a documentação da API, você pode contatar lifo no Github e pedir por direitos de commit no repositório docrails e enviar suas mudanças para o repositório. Por favor siga as convenções RDoc do docrails quando contribuir com mudanças.
5 O Wiki Rails
O wiki Rails é uma coleção de informações sobre o Rails geradas pelos usuários e aberta para edição. Ela abrange tudo desde começar com o Rails até FAQs, how-tos e plugins populares. Para contribuir com o wiki, simplesmente encontre alguma informação útil que ainda não esteja lá e adicione-a. Existem diretrizes de estilo para ajudar a manter o wiki um recurso coerente; veja a seção contribuindo para o wiki para mais detalhes.
6 Contribuindo para o Código do Rails
Quando você estiver pronto para aventurar-se, uma das formas mais úteis para contribuir para o Rails é efetivamente submeter código fonte. Aqui está um passo-a-passo das coisas que você precisa fazer para tornar esta uma experiência bem sucedida.
6.1 Aprenda a Linguagem e o Framework
Aprenda no mínimo alguma coisa sobre Ruby e Rails. Se você não compreender a sintaxe da linguagem, expressões comuns do Ruby, e o código que já existe no Rails, é improvável que você será capaz de criar um bom patch (isto é, um que será aceito). Você não tem que conhecer cada detalhe da linguagem e do framework; um pouco do código do Rails é extremamente complexo. Mas provavelmente o Rails não é apropriado como o primeiro lugar para escrever código Ruby. Você deve ao menos entender (embora não necessariamente memorizar) A Linguagem de Programação Ruby e ter navegado pelo código fonte do Rails.
6.2 Faça um Fork do Código Fonte do Rails
Faça um fork do Rails. Você não estará colocando seus patches diretamente no branch principal, OK? Aqui é onde você precisa daquela cópia do Rails que você clonou anteriormente. Pense em um nome para seu novo branch e execute
git checkout -b my_new_branch
Realmente não importa que nome você utilize, porque este branch existirá somente em seu computador local.
6.3 Escreva Seu Código
Agora ocupe-se e adicione seu código para o Rails (ou edite o código existente). Você está no seu branch agora, então pode escrever tudo que quiser (você pode verificar para ter certeza que está no branch correto com git branch -a). Mas se você está planejando submeter sua modificação de volta para inclusão no Rails, mantenha algumas coisas em mente:
- Obtenha o código certo
- Utilize as expressões e helpers do Rails
- Inclua testes que falhem sem o seu código, e passem com ele
- Atualize a documentação
6.4 Checagem de Sanidade
Você não deve ser a única pessoa que olha o código antes de enviá-lo. Você conhece ao menos um outro desenvolvedor Rails, certo? Mostre para ele o que você está fazendo e lhe peça um feedback. Fazer isto em particular, antes de enviar um patch publicamente, é o “teste de fumaça” para um patch: se você não pode convencer outro desenvolver da beleza de seu código, também é improvável que você convença a equipe core.
6.5 Faça um Commit de Suas Mudanças
Quando você estiver satisfeito com o código no seu computador, precisa fazer um commit das mudanças para o git:
git commit -a -m "Aqui está uma mensagem de commit"
6.6 Atualize o Rails
Atualize a sua cópia do Rails. É bastante provável que outras mudanças no core do Rails aconteceram enquanto você estava trabalhando. Vá pegá-las:
git checkout master
git pull
Agora reaplique seu patch sobre as últimas mudanças:
git checkout my_new_branch
git rebase master
Sem conflitos? Os testes ainda passam? A mudança ainda parece sensata para você? Então siga em frente.
6.7 Crie um Patch
Agora você pode criar um arquivo de patch para compartilhar com outros desenvolvedores (e com a equipe core do Rails). Ainda no seu branch, execute
git commit -a
git format-patch master --stdout > my_new_patch.diff
Faça um teste de sanidade nos resultados desta operação: abra o arquivo diff no editor de sua escolha e tenha certeza que nenhuma mudança não planejada apareceu.
6.8 Crie um Ticket no Lighthouse
Agora crie um ticket com seu patch. Vá para a página novo ticket no Lighthouse. Preencha um título e uma descrição sensatos, lembre-se de anexar seu arquivo de patch, e coloque a tag ‘patch’ no ticket e quaisquer outras tags relacionadas que fazem sentido.
6.9 Obtenha Algum Feedback
Agora você precisa fazer com que outras pessoas olhem seu patch, assim como você examinou os patches de outras pessoas. Você pode utilizar a lista de email rubyonrails-core ou o canal #rails-contrib no IRC freenode para isto. Você pode também apenas tentar falar com os desenvolvedores Rails que conhece.
6.10 Itere como for Necessário
É totalmente possível que o feedback que você terá irá sugerir mudanças. Não fique desencorajado: toda a razão de contribuir para um projeto open source ativo é explorar o conhecimento da comunidade. Se as pessoas estão encorajando você a mexer no seu código, então é valido fazer mudanças e reenviar. Se o feedback é que seu código não pertence ao core, você pode ainda pensar sobre lançá-lo como um plugin.
E então… pense sobre sua próxima contribuição!
7 Changelog
- 25 de Abril de 2009: Revisão da tradução para português por Eleudson Queiroz
- 24 de Março de 2009: Tradução para português por Carlos A. da Silva
- 2 de Março de 2009: Rascunho inicial por Mike Gunderloy