Projeto de Colaboração do Projeto CakePHP

UNIVERSIDADE FEDERAL DA BAHIA

Profª: Christina von Flach Garcia Chavez

Equipe: Debora Nascimento, Thiago Colares,

Thiago Souto, Vagner AmaralJunho de 2012 | Salvador,

Brasil

Sumário

• Introdução

• Seleção do Projeto

• Reconhecimento Inicial do CakePHP

• Identificação das tarefas do CakePHP

• Metodologia Geral para Contribuição

• Documentação

• Tradução

• Caracterização de Bugs / Implementação de Melhorias

• Testes

Sumário

• Análise Sobre Reabertura de Bugs

• Considerações Finais

• Referências

Introdução

• OSS - Open Source Software• Liberdade• Comunidades

• Objetivo• Participar em um Projeto de software Livre• Free Software Patterns (FSP)

• 2 Etapas• Seleção do projeto CakePHP• Colaboração com o projeto

Seleção do Projeto

• Análise de várias aplicações

• Seleção do CakePHP• Framework para o desenvolvimento rápido de

aplicações

• Segue o padrão MVC

Seleção do Projeto

• Um dos membros da equipe utiliza o CakePHP na sua empresa;

• Comunidade de usuários expressiva;

• A comunidade é bastante ativa;

• O projeto possui:• site oficial sempre atualizado;

• sistema para reportar bugs;

• documentação

• testes automatizados.

• Os artefatos do projeto são bem gerenciáveis;

• Oportunidade de aprendizado para a equipe

Reconhecimento Inicial do CakePHP

• Tecnologias utilizadaso PHP / JavaScript / DOS batch script / Shell script;o MySQL / Postgres / SQLite / SQL Server / NOSQLs

o Alguns Padrões Arquiteturais identificados:o MVC / ActiveRecord/ Association Data Mapping / Front

Controller

Reconhecimento Inicial do CakePHP

• Código-fonte do core do CakePHP (phploc)o Lines of Code (LOC): 215.713o Comment Lines of Code (CLOC): 63.796o Non-Comment Lines of Code (NCLOC): 151.917o Interfaces: 7o Classes: 962o Average Class Length (NCLOC): 161o Methods: 5563o Average Method Length (NCLOC): 27

Reconhecimento Inicial do CakePHP

• Licença do Projetoo MIT License (maior parte)o Open Group Teste Suite License

• Repositórioo Github: https://github.com/cakephp/cakephp

• Bugtrackero Lighthouse: http://cakephp.lighthouseapp.com/dashboard

o Suíte de Testes Automatizados: PHPUnit

Reconhecimento Inicial do CakePHP

• Política de Lançamento de Versõeso Uma versão por mêso Formato do número da versão X.Y.Z-<token>, no qual:

X = grande mudança no projeto; Y = pacotes de melhorias / novas funcionalidades; Z = nova versão estável <token> = alpha, beta ou RC#

Atuais: 2.1.3 (23/05/2012) e 2.2.0-RC2 (20/06/2012)

Identificação das Tarefas do CakePHP

• Tags dos tickets no Lighthouse

• Listas de tarefas pendentes no código-fonteo TODO (poucos. melhorias pontuais no código)

• Tarefas identificadas inicialmente:o Correção do bug relacionado à listagem feita com a

classe Paginate que utiliza Models diferentes;o Correção do bug relacionado à sinalização manual de

campos obrigatórios na classe FormHelper;

Metodologia Geral

• Tipos de atividade: o Documentaçãoo Traduçãoo Correção de Bugso Testes

• Para cada atividade:o caracterizar o projeto de acordo com as questões

disponibilizadas referentes a cada atividadeo escolher uma forma de contribuir com o projeto

escolhido no escopo da atividadeo submeter a contribuição para a comunidadeo relatar o feedback recebido da comunidade

• Uso dos FSP e dos Reengineering Patterns

Documentação [1]

• Padrões utilizados:o Skim The Documentation (Reengineering Patterns)o Write Documentation (Free Software Patterns)

• Localização da documentação do projetoo CookBook: http://book.cakephp.orgo API: http://api20.cakephp.orgo Bakery: http://bakery.cakephp.org

Documentação [2]

• Documentação adicional:o Visão geral sobre arquitetura

o http://book.cakephp.org/2.0/en/cakephp-overview/understanding-model-view-controller.html

o Estrutura Interna: o http://book.cakephp.org/2.0/en/getting-started/cakephp-structure.html

o Estrutura de Pastas: o http

://book.cakephp.org/2.0/en/getting-started/cakephp-folder-structure.html

o Bibliotecas: o http://book.cakephp.org/2.0/en/core-libraries.html

Documentação [3]

• Documentação adicional:o Tutoriais e exemplos:

o http://book.cakephp.org/2.0/en/tutorials-and-examples.html

o Orientações de como Colaborar com a Documentação:o http://book.cakephp.org/2.0/en/contributing/documentation.html

o Guia para formatação da documentação: o http://book.cakephp.org/2.0/en/contributing/documentation.html

o Padrões de Codificação: o http

://book.cakephp.org/2.0/en/contributing/cakephp-coding-conventions.html

Documentação [4]

• Documentação adicional:o Documentação para uso da suíte de testes (PHPUnit):

o http://book.cakephp.org/2.0/en/development/testing.html

o Documentação do processo de registro de Bugs:o http://book.cakephp.org/2.0/en/contributing/tickets.html

o Documentação do processo de envio de correções: o http://book.cakephp.org/2.0/en/contributing/code.html

o Outras informações para desenvolvedores: o http://cakephp.org/pages/development

Documentação [4.1]: IRC

• Contato direto com desenvolvedores do core

Documentação [4.1]: IRC

• Bin: ferramenta para compartilhar trechos de código http://bin.cakephp.org/

Documentação [4.1]: IRC

• CakeBot: log de todas as conversas do #cakephp http://irc.cakephp.org/

Documentação [5]

• Características o Formato de Texto: ReST (Re Structured Text) o Repositório: Github (http://github.com/cakephp/docs)o Equipe específica para documentação

Build ReST HTML

Make;Python;Sphinx;PhpDomainfor sphinx.

Documentação [6]

• Identificação de tarefas de documentaçãoo Diretiva antes do build para exibir TODO's no CookBook

Documentação [7]

• Tarefas identificadaso Add how to setup PATH for windows systems [1]

Documentação [8]

• 1º Ciclo completo do processo de colaboração• Passo 1: Configuração Inicial (Git/GitHub)

• Passo 2: Fork

• Passo 3:Clone

Documentação [8]

• 1º Ciclo completo do processo de colaboração• Passo 4: Modificações (direto no GitHub)

View Edit / Commit

Documentação [8]

• 1º Ciclo completo do processo de colaboração• Passo 5: Pull Request

Documentação [8]

• Tarefas identificadas (resolução)o Add how to setup PATH for windows systems [2]

Tradução [1]

• Tradução do Core ou de uma Aplicação• Ferramentas Utilizadas

• Arquivos POT: template;

• Arquivos PO: tradução propriamente dita;

• i18n shell (comando extract) para geração do arquivo POT;

• PoEdit para manipulação do arquivo PO;

• Situação do Core• Internacionalizado (i18n), mas não localizado (L10n)

• Situação da Aplicação padrão• Não era relevante traduzir

• Não havia iniciativas da comunidade

• Equipe optou por focar na Documentação

Tradução [2]

• Várias orientações aos tradutores [1]• Use linguagem informal, não faça traduções parciais

etc.

• Idiomas disponíveis CookBooko espanhol;o francês;o japonês;o russo;o português;

• Equipe:o Há um colaborador ativo residente em Salvador / Bahia

que atua na tradução do CookBook para pt-BR;

[1] http://book.cakephp.org/2.0/en/contributing/documentation.html

Tradução [3]

• Identificação das atividades:o Contato com a equipe responsável pela tradução pt-BR;o Investigação do repositório no Github;o Análise do CookBook em busca de itens com pouca

informação em pt-BR (se comparado com en-US);

• Atividade escolhida: tradução da página principal da seção "Views" do CookBook.• Não existia!

• Conteúdo relevante

Tradução [4]

• Seção "Views" em en:

{

Tradução [5]

• Seção "Views" em pt:

{

Tradução [6]

• Feedback da tradução da seção "Views" do CookBook para pt:

Caracterização de Bugs / Implementação de

Melhorias• Bugtracker: Lighthouse

• http://cakephp.lighthouseapp.com/dashboard

• Registro de Ticketso Ciclo de Vida do ticket de um projeto:

o http://cakephp.lighthouseapp.com/core-contributor-guidelines

• Informações encontradas no Registro de Tickets:o Descrição do problema;o Comportamento esperado;o Comportamento obtido;o Passos para reprodução do bug;o Versão do CakePHP em que o bug foi identificado;o Possíveis soluções;

Caracterização de Bugs / Implementação de

Melhorias• Critérios utlizados para identificação dos bugs /

melhorias:o Desenvolvedores validaram o ticket como realmente

um bug / melhoria;o Descrição objetiva do bug / melhoria.o Conhecimento sobre área do código que está

ocorrendo o bug / melhoria.o Avaliação superficial e subjetiva se a tarefa pode ser

realizada em um curto espaço de tempo.

• A partir dos critérios, foi gerada uma lista com vários itens obtidos no Lighthouse. Após a análise de cada um dos itens, três deles foram escolhidos.

Caracterização de Bugs / Implementação de

Melhorias• Ticket 2787

Caracterização de Bugs / Implementação de

Melhorias• Ticket 2787

o Criação de um clone do fork no Github;https://github.com/colares/cakephp/tree/ticket-2787

o Atualização dos casos de teste;o Via de regra, a comunidade CakePHP só aceita patches

acompanhados de casos de estes

o Dificuldades na comunicação do PHPUnit (quando instalado via Pear) com o CakePHP. o Uso do plugin desenvolvido por Stef van den Ham https://

github.com/Hyra/PHPUnit-Cake2

o Pull request foi aceito pela comunidade

Caracterização de Bugs / Implementação de

Melhorias • Ticket 2787: feedback positivo.

Caracterização de Bugs / Implementação de

Melhorias• Ticket 2787: modificação já está no CookBook.

Caracterização de Bugs / Implementação de

Melhorias• Ticket 2851: método year não ordena

Caracterização de Bugs / Implementação de

Melhorias• Ticket 2851

o A equipe verificou o erro e constatou:o O erro não era válido, pois não existiao A solução constava na documentação

o No final, o ticket foi marcado como "works-for-me".

Caracterização de Bugs / Implementação de

Melhorias• Ticket 2851

Caracterização de Bugs / Implementação de

Melhorias • Ticket 2894

o O usuário apontou um possível erro existente em um método do HelperForm usado para criar botões HTML do tipo submit;

o A equipe interagiu com a comunidade na validação do ticket;o Foi descaracterizado como um o e foi marcado como "wont-fix”.

o Sinaliza um ponto de refatoração

Caracterização de Bugs / Implementação de

Melhorias • Ticket 2894

Testes

• Verificações empregradas no projeto (visão geral)

“new"

Válido?

“duplicate”, “wont-fix”,

“works-form-me” ou “invalid”

NãoNovo Ticket

Validação

Sim

Confirmação?

Confirmação

“closed"

Esclare-cido?

Não

“open"“hold"

Discussões

Sim

RevisõesMilestonesTagsDiscussõesEtc…

“resolved"

Inicia-seResolução

Conclusão

Ações Estados Verificação

Testes: Verificação em pull requests

• Funcionou?• Seguiu padrões de codificação?• Enviou casos de testes?

Testes: CakePHP + PHPUnit

• CakePHP provê integração com PHPUnito A principal ferramenta para testes unitários em PHPo Prover visualização de cobertura etc.

• Fixtures• banco com dados temporários

• Mock objects• Integração com Jenkins

o Servidor para automatizar o processo de construção (build), implantação;

Testes: Como realiza-los?

• Seguir padrões de pastas e nomeclaturas• Instalar PHPUnit

o Via PEAR ou como plugin do CakePHP [1]

• Interface web

[1] https://github.com/Hyra/PHPUnit-Cake2

Testes

Implementação de casos de teste

Testes

Verificação dos casos de teste

Análise Sobre Reabertura de Bugs

• Ausência de um estado "reopen" no Lighthouse;

• Pesquisa feita no Google utilizando a seguinte expressão:• site:cakephp.lighthouseapp.com "State changed from

“resolved” to “open”"

Análise Sobre Reabertura de Bugs

• Alguns resultados obtidos• Ticket - #2031

• Resolvido – September 27th, 2011 @ 04:39 PM

• Por - Admad

• Reaberto – September 27th, 2011 @ 04:44 PM

• Por - Admad

• Causa• Pensou que o bug era similar a outro ticket resolvido

anteriormente (ADmad: Oops .DS_Store is a file, not directory.)

• Re-resolvido - September 27th, 2011 @ 07:44 PM

• Por – Mark Story

Análise Sobre Reabertura de Bugs [3]

• Alguns resultados obtidos• Ticket – #2931

• Resolvido – June 3rd, 2012 @ 09:24 PM

• Por - Rachman Chavik

• Reaberto – June 4th, 2012 @ 11:24 AM

• Por - Rachman Chavik

• Causa• Próprio colaborador revisou e viu que a correção foi

incompleta. Mas o erro ainda continua sem solução. (Rachman Chavik: reopening, due to incomplete fix.)

• Re-resolvido –

• Por -

Análise Sobre Reabertura de Bugs

• Alguns resultados obtidos• Ticket – #2857

• Resolvido – May 6th, 2012 @ 09:49 PM

• Por - CakePHP (Mark Story, github)

• Reaberto – May 7th, 2012 @ 08:59 AM

• Por - Mark Story

• Causa• Próprio colaborador revisou e viu que a correção foi

incompleta. Mesmo após a mudança do status para resolved, outros commits relacionados ao mesmo erro foram realizados. (Mark Story: I think I might have not done a thorough enough test of this, and it also broke the postgres build. Re-opening until those issues are fixed.)

• Re-resolvido – May 7th, 2012 @ 08:49 PM

• Por - CakePHP (Mark Story, github)

Análise Sobre Reabertura de Bugs

• Alguns resultados obtidos• Ticket – #2174

• Resolvido – October 27th, 2011 @ 09:53 AM

• Por - Admad ("Afaik this bug doesn't exist in 1.x“)

• Reaberto – October 27th, 2011 @ 09:53 AM

• Por - Admad

• Causa• O desenvolvedor e o usuário que reportou o erro estavam

trabalhando com versões diferentes. Após o erro ter sido reaberto, foi marcado como duplicado, para finalmente ser marcado para resolvido. (Milestone changed from “2.0.1” to “1.3.13”. Oh i presumed you were reporting it for 2.0. Depois Mark Story fez: State changed from “open” to “duplicate”)

• Re-resolvido – March 23rd, 2012 @ 08:21 PM

• Por - Mark Story

Análise Sobre Reabertura de Bugs

• Alguns resultados obtidos• Ticket – #1084

• Resolvido – July 15th, 2011 @ 06:03 PM

• Por - Jose Lorenzo Rodríguez

• Reaberto – July 15th, 2011 @ 08:01 PM

• Por - Mark Story

• Causa• Um dos desenvolvedores informou que o comportamento

em questão seria modificado a partir da refatoração de uma classe. Por isso, o bug foi marcado como resolved. No entanto, como isso ainda não havia sido feito, o outro desenvolvedor retornou o estado do ticket novamente para open. (I actually haven't made the time to finish this off. Currently behaviors still go into ClassRegistry

• Milestone changed from “2.0.0” to “Future)

Análise Sobre Reabertura de Bugs

• Alguns resultados obtidos• Ticket – #2103

• Resolvido – October 14th, 2011 @ 08:25 PM

• Por - CakePHP (Mark Story, github)

• Reaberto – October 19th, 2011 @ 09:46 PM

• Por - Mark Story (erro reportado por EärendilI)

• Causa• No passo inícial, o erro foi considerado inválido, ou seja, houve

uma falha na compreensão do problema. Posteriormente, o problema passou por vários passos de open/resolved, em virtude do problema não estar totalmente corrigido

• Re-resolvido – October 19th, 2011 @ 10:09 PM

• Por - CakePHP (Mark Story, github)

Considerações Finais

• Importância da colaboração com as comunidades mantenedoras dos projetos

• Conhecimento prévio do projeto e da comunidade facilitaram a colaboração;

o O desconhecimento por uma parte da equipe dificultou a colaboração com código

• O aprendizado foi grande, devido ao caráter prático das atividades

• A maturidade do projeto e a farta documentação facilitaram as novas colaborações• CookBook, IRC, Github, Lighthouse, Grupo de

Discussão.

Lições Aprendidas

• Desenvolvedores do core muito ativos deram feedbacks rápidos e atenciosos

o Contrariando o que se especulou

• O IRC foi uma poderosa ferramenta

Trabalhos Futuros

• Publicar resultados na comunidade;

• Colaborar na tradução das seções restantes do CookBook para pt;

• Localizar (L10n) o core para Português (BR);

• Analisar os pontos do core encontrados e que são passíveis de refatoração;

• Incluir mais informações extraídas do Doxygen na documentação da API (e.g. diagrama de classes)

• Analisar melhor cobertura de testes do código do core;

Perguntas, Críticas, Sugestões?