- O documento descreve a colaboração de uma equipe da Universidade Federal da Bahia em projetos de código aberto, especificamente no framework PHP CakePHP. - A equipe selecionou o CakePHP para colaboração depois de analisar várias opções e considerar aspectos como tamanho da comunidade, atividade e qualidade dos artefatos. - As atividades de colaboração incluíram documentação, tradução, identificação e correção de bugs utilizando a metodologia e padrões de contribuição do projeto CakePHP.

1. UNIVERSIDADE FEDERAL DA BAHIA
Colaboração em Projetos
FLOSS1: CakePHP
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

2. 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

3. Sumário
• Análise Sobre Reabertura de Bugs
• Considerações Finais
• Referências

4. 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

5. 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

6. 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

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

8. Reconhecimento Inicial do
CakePHP
• 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

9. Reconhecimento Inicial do
CakePHP
• 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

10. Reconhecimento Inicial do
CakePHP
• 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)

11. 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;

12. 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

13. 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

14. 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

15. 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

16. 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

17. Documentação [4.1]: IRC
• Contato direto com desenvolvedores do core

18. Documentação [4.1]: IRC
• Bin: ferramenta para compartilhar trechos de
código http://bin.cakephp.org/

19. Documentação [4.1]: IRC
• CakeBot: log de todas as conversas do #cakephp
http://irc.cakephp.org/

20. 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.

21. Documentação [6]
• Identificação de tarefas de documentação
o Diretiva antes do build para exibir TODO's no CookBook

22. Documentação [7]
• Tarefas identificadas
o Add how to setup PATH for windows systems [1]

23. Documentação [8]
• 1º Ciclo completo do processo de colaboração
• Passo 1: Configuração Inicial (Git/GitHub)
• Passo 2: Fork
• Passo 3:Clone

24. Documentação [8]
• 1º Ciclo completo do processo de colaboração
• Passo 4: Modificações (direto no GitHub)
View Edit / Commit

25. Documentação [8]
• 1º Ciclo completo do processo de colaboração
• Passo 5: Pull Request

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

27. 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

28. 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

29. 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

30. Tradução [4]
{
• Seção "Views" em en:

31. Tradução [5]
• Seção "Views" em pt:
{

32. Tradução [6]
• Feedback da tradução da seção "Views" do
CookBook para pt:

33. 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;

34. 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.

35. Caracterização de Bugs /
Implementação de Melhorias
• Ticket 2787

36. 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

37. Caracterização de Bugs /
Implementação de Melhorias
• Ticket 2787: feedback positivo.

38. Caracterização de Bugs /
Implementação de Melhorias
• Ticket 2787: modificação já está no CookBook.

39. Caracterização de Bugs /
Implementação de Melhorias
• Ticket 2851: método year não ordena

40. 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 existia
o A solução constava na documentação
o No final, o ticket foi marcado como "works-for-me".

41. Caracterização de Bugs /
Implementação de Melhorias
• Ticket 2851

42. 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

43. Caracterização de Bugs /
Implementação de Melhorias
• Ticket 2894

44. Testes
• Verificações empregradas no projeto (visão geral)
“duplicate”, “wont- Confirmação
fix”, “works-form-
me” ou “invalid” Confir “closed"
mação?
Novo Validação
Ticket
“new" Válido?
Sim
Revisões
Milestones
Discussões Esclare Tags
-cido?
Discussões
Etc…
Inicia-se Conclusão
Resolução
“hold" “open" “resolved"
Ações Estados Verificação

45. Testes: Verificação em pull
requests
• Funcionou?
• Seguiu padrões de codificação?
• Enviou casos de testes?

46. 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;

47. 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

48. Testes
Implementação de casos de teste

49. Testes
Verificação dos casos de teste

50. 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”"

51. 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

52. 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 -

53. 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)

54. 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

55. 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)

56. 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)

57. 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.

58. 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

59. 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.

60. Perguntas, Críticas, Sugestões?