Metodologia de Uso do Trac e Subversion no Expresso

O uso do controlador de configurações Trac e do controlador de versões Subversion é essencial para realizar um bom gerenciamento de projetos onde há muitos participantes envolvidos, e no caso do expressoLivre, isto se faz ainda mais relevante pois há diversas empresas fazendo a todo instante um commit das suas implementações no repositório.

Este documento tem por objetivo disciplinar a utilização dessas duas ferramentas a fim de diminuir problemas comuns como a sobreposição de códigos ou a dificuldade de rastrear soluções.

Abertura de Tickets

Na abertura de um ticket o mais importante é que deve haver um e somente um ticket para cada problema, por menor que o problema seja, isto porque os procedimentos executados e os códigos vinculados a este problema serão facilmente rastreados posteriormente, o que facilitará a análise futura de como tal problema foi solucionado.

Obviamente que haverá tickets com várias tarefas a serem feitas, como por exemplo criar módulo de relatórios, neste caso a resolução desse ticket será composta de uma série de códigos novos. Isto não será um problema desde que o ticket seja fechado somente quando o módulo como um todo tiver sido finalizado, pois aí os códigos vinculados ao ticket surgirão todos em função da criação do tal módulo.

O caso de tickets que devem ser evitados a todo custo, são aqueles cujos problemas são claramente distintos, por exemplo: corrigir funcionalidades de anexo de arquivos e inserção de imagem no corpo da mensagem no expressoMail. Neste caso o que acontecerá na resolução deste ticket é que não ficarão distintas as alterações que foram feitas para resolver cada um dos problemas. O correto nesta situação é criar um ticket para resolver o problema dos anexos e um outro para a inserção de imagem.

Um outro detalhe sobre a abertura de tickets é que o mesmo deve conter o máximo de inofrmações sobre problema. Se a criação de um ticket for em função de um defeito, o criador do ticket deve inserir no detalhe todos os passos que o solucionador deve executar para forçar o erro. Assim ficará claro qual é o problema e como fazer para o mesmo aparecer.

Uso do Subversion

A utilização correta do Subversion com o Trac é que irá permitir utilizar um grande recurso que esta ferramenta oferece para os desenvolvedores, a rastreabilidade. No entanto, para que isto seja possível é necessário disciplinar as rotinas de utilização do svn, lembrando que isto não se resume apenas as operações de update e de commit embora na prática estas sejam as mais utilizadas.

Após a operação de checkout (svn co) que executa a criação da área de trabalho, inicia-se resolução de um ticket, neste momento o desenvolvedor terá a área de trabalho com a última versão de todos os arquivos do repositório. Uma vez resolvido o problema é necessário fazer um update, para verificar se neste meio tempo não houve alteração dos arquivos no repositório, se houve o próprio svn se encarrega de fazer a atualização dos arquivos.

No momento em que o svn faz a atualização dos arquivos pode acontecer um merge de códigos, caso as modificações tenham sido feitas em um mesmo arquivo. Outra situação comum que acontece quando muitas pessoas estão trabalhando no projeto é o conflito. Quando isso ocorre o subversion avisa que o conflito ocorreu e gera três arquivos para auxiliar a solucionar o conflito. Resolvido o conflito (vide Apêndice A) o desenvolvedor poder continuar trabalhando normalmente e por último executar um commit dos códigos alterados na sua área de trabalho local.

Importante todo commit deve ser precedido de um update. Todo commit deve ser executado somente quando um problema foi resolvido, ou seja, as alterações registradas neste commit fecham um ticket, de maneira que todo ticket fechado tenha um número de revisão correspondente no subversion. O SVN não deve ser encarado como backup, portanto não se deve executar um commit para um problema meio resolvido.

Na execução do commit que irá fechar um ticket a linha de comando deve ser a seguinte:

svn ci -m “resolve #<número-do-ticket-que-está-sendo-fechado>”

O parâmetro -m é utilizado para registro de log do commit. Neste log devem ser utilizadas as palavras reservadas Resolve e Corrige. Resolve indica o término da solução de um ticket. Corrige indica a retificação da solução de um ticket que foi fechado e depois reaberto pois a primeira solução foi falsa, incompleta, ou resultou em um efeito colateral. Seguido da palavra reservada deve ser usado o caracter # mais o número do ticket que está sendo fechado, com isto faz-se a amarração do ticket do Trac com o número da revisão do Subversion criando a tão necessária rastreabilidade, sendo portanto necessário anotar o número da revisão do repositório após o commit pois isto deverá ser utilizado no fechamento do ticket.

Não se deve armazernar no registro de log do commit nenhuma outra informação, pois isto acaba poluindo o registro exibido no Trac. Caso seja necessário inserir maiores detalhes sobre a solucão do ticket, isto deve ser posto no campo de comentário do Trac (comment) que cada ticket dispõe.

Fechamento de Tickets

O fechamento deve ser feito via de regra somente após o commit no svn, pois será necessário o número da revisão do repositório para que a amarração entre o trac e o svn seja feita corretamente. Sendo assim devem ser utilizadas as frases reservadas "Implementado em" ou "Corrigido em". Implementado em indica o fechamento do ticket. Corrigido em indica a correção de um ticket que foi fechado e depois reaberto decorrente de algum problema no seu fechamento. Seguido da frase reservada deve ser usado entre colchetes o número da revisão do repositório que corresponde ao commit executado, exemplo:

Implementando em [6]
...
Corrigido em [12]

Com isto o Trac cria um link do que em está entre colchetes com a revisão svn dos códigos, e fica fácil então encontrar quais arquivos foram modificados para resolver o ticket.

Uma consideração importante, é responsabilidade exclusiva do desenvolvedor executar estes procedimentos da forma como foram descritos, utilizando as palavras e frases reservadas, fazendo referência no svn ao ticket e no trac a revisão no svn. Caso contrário o processo de solução dos tickets se perderá, tendo o gerente do projeto ou mesmo o desenvolvedor localizar as mudanças vi timeline, o que não é lá uma tarefa muito agradável.

Apêndice A - Resolvendo Conflitos no Subversion

Para enteder melhor como isto é feito, tomemos o exemplo a seguir. O usuário "A" faz um checkout (svn co), inicia os seus trabalhos fazendo modificações no(s) arquivo(s). Enquanto isto o usuário "B" também faz um checkout, faz as modificações no(s) mesmo(s) arquivo(s) e na(s) mesma(s) linha(s) que o usuário "A", e ao encerrar a sua tarefa, primeiro que o usuário "A", executa um commit (svn ci). Nesta situação o usuário "A" ao tentar fazer um commit será avisado que o(s) arquivo(s) que ele modificou está com versão diferente do repositório.

Sendo assim, o que o usuário "A" deve fazer é um update (svn up). Neste momento o svn fará o seguinte, imaginemos que o arquivo modificado e que possui o conflito é o listas.txt, ele modificará o arquivo listas.txt inserindo nele as diferenças da versão que está no repositório. Além desta modificação serão criados outros três arquivos: listas.txt.mime, é o arquivo listas.txt original do usuário "A"; listas.txt.r<revisão-anterior>, é o arquivo da revisão anterior a trabalhada pelo usuário "A"; listas.txt.r<última-revisão>, é o arquivo na última versão.

Dependendo da quantidade de diferenças pode-se editar o arquivo listas.txt e retirar as marcações deixando-o pronto para commit, caso as diferenças sejam muitas e em diversas partes do arquivo deve-se utilizar uma ferramenta gráfica de diff (meld ou kdiff3) e abrir os arquivos listas.txt.mime e listas.txt.r<última-revisão>. Resolvidas as diferenças, o arquivo deverá ser salvo como sendo listas.txt, pois é o único que está sob controle de versão. Após isto o comando de resolução do conflito, que "diz" ao svn que o conflito foi resolvido, que deve ser executado é svn resolved listas.txt, ao executar este comando os outros arquivos serão excluídos pelo próprio svn. Por fim o usuário "A" faz um commit normal.