Colaboração em Projetos FLOSS: CakePHP

Colaboração em Projetos FLOSS1: CakePHP

UFBA / UEFS

Profª: Christina von Flach Garcia Chavez

Equipe: Debora Nascimento, Thiago Colares,

Thiago Souto, Vagner Amaral

Junho de 2012 | Salvador, Brasil

1: Free/Libre/Open Source Software

Sumário

•  Introdução •  Seleção do Projeto •  Reconhecimento Inicial do CakePHP

•  Metodologia Geral para Contribuição •  Documentação •  Tradução •  Caracterização de Bugs / Implementação de Melhorias

•  Testes •  Análise Sobre Reabertura de Bugs •  Considerações Finais

Sumário

•  Análise Sobre Reabertura de Bugs •  Considerações Finais

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 utilizadas o  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


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


•  Licença do Projeto o  MIT License (maior parte)

o  Open Group Teste Suite License

•  Repositório o  Github: https://github.com/cakephp/cakephp

•  Bugtracker o  Lighthouse: http://cakephp.lighthouseapp.com/dashboard

o  Suíte de Testes Automatizados: PHPUnit


•  Política de Lançamento de Versões o  Uma versão por mês o  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-fonte

o  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ção o  Tradução o  Correção de Bugs o  Testes

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

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

escolhido no escopo da atividade o  submeter a contribuição para a comunidade o  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 projeto o  CookBook: http://book.cakephp.org o  API: http://api20.cakephp.org o  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


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


•  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; PhpDomain for sphinx.

Documentação [6]

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

Documentação [7]

•  Tarefas identificadas o  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 CookBook o  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 Tickets o  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


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


o  A equipe verificou o erro e constatou: o  O erro não era válido, pois não existia

o  A solução constava na documentação

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



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


Testes

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

“new" Válido?

“duplicate”, “wont-fix”, “works-form-me” ou “invalid”

Novo Ticket

Validação

Sim

Confirmação?

Confirmação

“closed"

Esclare-cido?

“open" “hold"

Discussões

Revisões Milestones Tags Discussões Etc…

“resolved"

Inicia-se Resoluçã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 PHPUnit o  A principal ferramenta para testes unitários em PHP o  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”"


•  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 -


•  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)


•  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


•  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)


•  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

•  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 (em inglês); •  Revisar colaborações com o padrão utilizado; •  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?

Technology

Colaboração em Projetos FLOSS: CakePHP