wiki:Projeto/MetodologiaUsoTracSubversion

Version 17 (modified by niltonneto, 15 years ago) (diff)

--

Metodologia de Uso do Trac e Subversion no Expresso

Objetivo

O uso de um sistema para controle de mudanças em projetos de desenvolvimento de software, e de um sistema de controle de versões é essencial para realizar um bom gerenciamento de projetos onde há muitos participantes envolvidos. No caso do Expresso Livre, isto torna-se ainda mais relevante quando há diversas empresas fazendo a todo instante um commit das suas implementações em um mesmo repositório.

Este documento tem por objetivo disciplinar a utilização dessas duas ferramentas, no nosso caso foi adotado o Trac e o Subversion respectivamente, 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 informações sobre o 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. Além disso, o desenvolvedor deve informar o ambiente, cliente e servidor, no qual o erro foi reproduzido com êxito.

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:

Implementado 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 via timeline, o que não é lá uma tarefa muito agradável.

Reabertura de Tickets

A reabertura de um determinado ticket é permitida somente se tal implementação/correção ainda não foi publicada em alguma versão (Tag ou Branch). Caso o ticket fechado estiver atrelado a um marco (Milestone) que também já foi fechado, isso significa que a versão já foi publicada, e portanto, sua alteração terá ter um novo ticket para ser comitada no SVN.

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.

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

svn ci -m “Ticket #000 - <descrição com no mínimo 40 e no máximo 100 caracteres>”

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, ou seja, não se deve executar um commit para um problema meio resolvido, pois ele deve ser atômico.

O parâmetro -m é utilizado para registro de log do commit, seguido da palavra Ticket, mais o número do ticket que está sendo fechado, precedido pelo caracter #. Após o número do ticket, descrever de forma suscinta, entre 40 e 100 caracteres, um texto contendo informações a respeito da alteração feita no código SVN. 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 logo após o commit uma vez que tal informação deverá ser registrada no fechamento do ticket.

 Resumo das regras para commits:
a) NUNCA efetue um commit sem comentário.
a) Todo commit deve estar atrelado a um ticket do Trac. Caso ainda não exista um ticket, abri-lo antes de efetuar o commit;
b) Todo commit deve respeitar o seguinte formato: Ticket #000 - <descrição com no mínimo 40 e no máximo 100 caracteres>
c) Se for um bug referente a alguma funcionalidade/tarefa/melhoria que ainda não foi versionada (publicada no site), utilize o mesmo ticket.
d) Se for um bug referente a alguma funcionalidade/tarefa/melhoria que já foi versionada (publicada no site), abra um novo ticket.

Não se deve armazenar no registro de log do commit nenhuma informação que fuja do objetivo principal abordado. Isso é muito importante porque as versões dos pacotes, quando publicadas, irão conter um arquivo changelog.txt, gerado automaticamente a partir dos dados armazenados nesse registro de log. 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.

Por fim, o SVN contém um script pre-commit para assegurar o formato padrão do comentário no momento do commit. Caso esse formato não seja respeitado, um erro será retornado ao cliente SVN e a operação de commit será cancelada.

Apêndice A - Resolvendo Conflitos no Subversion

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

Apêndice B - Dicas de Utilização do SVN

Link interessante para quem quer começar a usar o repositório =>  SVN :: Como começar
Manual de utilização do SubVersion? (muito bom!!!) =>  svn-book.pdf