É muito comum no desenvolvimento de Software que as alterações possam ser relacionadas com um problema ou bug específico. Os utilizadores dos sistemas de identificação de bugs (gestores de problemas) gostariam de associar a alterações que fazem no Subversion, com um ID específico, no seu sistema de gestão de problemas. A maioria dos gestores de problemas providencia um script de gancho pre-commit que analisa a mensagem de registo de modo a encontrar o ID do bug, com o qual a submissão está associada. Isto é algo sujeito a erros, visto que confia que o utilizador escreva uma mensagem de registo correcta, para que o script de gancho pre-commit o possa analisar correctamente.
O TortoiseSVN pode ajudar o utilizador de duas maneiras:
Quando o utilizador introduz a mensagem de registo, pode ser automaticamente adicionada uma linha bem definida, que incluí o número de problema associado com a submissão. Isto irá reduzir o risco de que o utilizador introduza um número de problema de uma maneira tal que, as ferramentas de identificação de bugs não o consigam analisar correctamente.
Ou o TortoiseSVN poderá salientar a parte da mensagem inserida, que é reconhecida pelo gestor de problemas. Dessa maneira o utilizador saberá que a mensagem de erro pode ser correctamente analisada.
Quando o utilizador navega nas mensagens de registo, o TortoiseSVN cria uma hiperligação a partir de cada ID de bug na mensagem de erro, que aponta o navegador de internet para o problema mencionado.
Tu podes integrar a ferramenta de controlo de problemas da tua escolha com o TortoiseSVN. Para o fazer, terás de definir algumas propriedades que começam por bugtraq:. Estas deverão ser colocadas nas pastas: (“Configurações de Projecto”)
Quando editas qualquer uma das propriedades do bugtraq, um editor de propriedade especial será usado para tornar mais fácil definir os valores adequados.
Existem duas maneiras de integrar o TortoiseSVN com os gestores de problemas. Um é baseado em cadeias de caracteres simples, a outra é baseado em expressões regulares. As propriedades usadas em ambas as abordagens são:
- bugtraq:url
Configura esta propriedade para o URL da tua ferramenta de controlo de problemas. Deverá ser um URI devidamente codificado, e terá de conter
%BUGID%. O%BUGID%é substituído pelo número de problema que introduzires. Isto permite ao TortoiseSVN mostrar uma hiperligação na caixa de diálogo de registo, para quando estiveres a olhar para o registo de revisões possas saltar directamente para a tua ferramenta de identificação de bugs. Não precisas de providenciar essa propriedade, mas então o TortoiseSVN apenas mostrará o número do problema e não a hiperligação para a tua ferramenta de controlo de problemas. E.g. o projecto TortoiseSVN está a usar ohttp://issues.tortoisesvn.net/?do=details&id=%BUGID%.Poderás também usar URLs relativos em vez de absolutos. Isto é útil quando o teu gestor de problemas está no mesmo domínio/servidor que o teu repositório de fontes. No caso do nome de domínio se alterar, tu não precisarás de ajustar a propriedade
bugtraq:url. Existem então duas maneiras de especificar um URL relativo:If it begins with the string
^/it is assumed to be relative to the repository root. For example,^/../?do=details&id=%BUGID%will resolve tohttps://tortoisesvn.net/?do=details&id=%BUGID%if your repository is located onhttps://tortoisesvn.net/svn/trunk/.A URL beginning with the string
/is assumed to be relative to the server's hostname. For example/?do=details&id=%BUGID%will resolve tohttps://tortoisesvn.net/?do=details&id=%BUGID%if your repository is located anywhere onhttps://tortoisesvn.net.- bugtraq:warnifnoissue
Fixa este a
truese queres que o TortoiseSVN te avise, que o campo de texto do número-de-problema está vazio. Valores válidos sãotrue/false. Se não definido é assumido o valorfalse.
Na abordagem mais simples o TortoiseSVN mostra ao utilizador um campo de entrada separado onde o ID do bug pode ser introduzido. Então uma linha separada é pre/pós anexada à mensagem de registo que o utilizador introduziu.
- bugtraq:message
Esta propriedade activa o sistema de controlo de problemas no modo Campo de Entrada. Se esta propriedade é fixada então o TrotoiseSVN ir-te-á pedir para introduzires o número de problema quando submeteres as tuas alterações. Será usado para adicionar uma linha no fim da mensagem de registo. Deverá conter
%BUGID%, que será substituído pelo número de problema que introduzires ao submeter. Isto garante que teu registo de submissão contém uma referência ao número de problema, que estará sempre num formato consistente e poderá ser analisado pela tua ferramenta de identificação de problemas, de forma a associar o número de problema com uma submissão particular. Como exemplo poderás usarIssue : %BUGID%, mas tal dependerá da tua ferramenta.- bugtraq:label
Este texto é mostrado pelo TortoiseSVN na caixa de diálogo submeter, para etiquetar a caixa de edição onde irás introduzir o número do problema. Se não fixado, será mostrado
Bug-ID / Issue-Nr:. Tem em mente que a janela não será redimensionada para acomodar esta etiqueta, pelo que, mantém o tamanho da etiqueta abaixo dos 20-25 caracteres.- bugtraq:number
Se configurado a
truesó serão permitidos números no campo de texto do número-de-problema. Uma excepção é a vírgula para que possas separar vários números. Valores válidos sãotrue/false. Se não definido, é assumidotrue.- bugtraq:append
Esta propriedade define se o bug-ID é anexado (true) ao fim da mensagem de registo ou inserido (false) no início da mensagem de registo. Valores válidos são
true/false. Se não definido, é assumido o valortruepara que os projectos já existentes não sejam danificados.
Na abordagem com as expressões regulares, o TortoiseSVN não mostra um campo de entrada separado, mas marca a parte da mensagem de registo que o utilizador introduz, e que é reconhecida pelo controlador de problemas. Isto é efectuado enquanto o utilizador escreve a mensagem de registo. Também significa que o ID do problema pode estar algures dentro da mensagem de registo! Este método é muito mais flexível e é o utilizado pelo próprio projecto do TortoiseSVN.
- bugtraq:logregex
Esta propriedade activa o sistema de controlo de bugs no modo Regex. Ele contém uma única expressão regular ou duas expressões regulares separadas por uma nova linha.
Se são colocadas duas expressões, então a primeira é usada como um pré-filtro para encontrar as expressões que contêm os IDs dos problemas. A segunda expressão extrai então os IDs dos bugs encontrados a partir do resultado da primeira regex. Isto permite-te usar uma lista de IDs de problemas e as expressões que desejes, em linguagem natural. E.g. poderás resolver vários problemas e incluir uma string com esta: “Esta alteração resolve os assuntos #23, #24 e #25”.
Se queres apanhar os IDs dos problemas, como é usado na expressão acima dentro da mensagem de registo, poderás usar as seguintes strings regex, que são as usadas pelo projecto TortoiseSVN:
[Ii]ssues?:?(\s*(,|and)?\s*#\d+)+and(\d+).A primeira expressão pega nos “assuntos #23, #24 and #25” a partir da mensagem de registo circundante. A segunda regex extrai simples números decimais a partir da saída da primeira regex, pelo que irá retornar “23”, “24” e “25” para serem usados como IDs de problemas.
Dividindo um pouco a primeira regex, esta deve começar com a palavra “issue”, e possivelmente em maiúsculas. Esta é opcionalmente seguida por um “s” (mais de um assunto) e também opcionalmente por dois pontos. Isto é seguido por um mais grupos, cada um tendo à frente zero ou mais espaços em branco, e um opcionalmente uma vírgula ou “and” e mais espaços opcionais. Finalmente existe um “#” obrigatório e um também obrigatório número decimal.
Se só for usada uma expressão, então os IDs dos problemas descobertos terão de ter correspondência nos grupos da string regex. Exemplo:
[Ii]ssue(?:s)? #?(\d+)Este método é requerido por alguns controladores de assuntos, e.g. trac, mas é mais difícil a construção da regex. Nós recomendamos que só uses este método se a documentação do teu controlador de assuntos te disser para o fazer.If you are unfamiliar with regular expressions, take a look at the introduction at https://en.wikipedia.org/wiki/Regular_expression, and the online documentation and tutorial at http://www.regular-expressions.info/.
Não é sempre fácil obter a regex correcta, pelo que para dar ajudar, existe uma caixa de diálogo de teste embebida na caixa de diálogo de propriedades do bugtraq. Clica no botão à direita das caixas de edição para o mostrar. Aqui podes introduzir algum texto, e alterar cada regex para veres os resultados. Se a regex for inválida o fundo da caixa de edição muda para vermelho.
Se ambas as propriedades bugtraq:message e bugtraq:logregex estão configuradas, toma precedência a logregex
Dica
Mesmo que não tenhas um controlador de assuntos, com um gancho de pré-submissão a analisar a tua mensagem de registo, poderás ainda usar isto para converter os assuntos mencionados nas tuas mensagens de registo em hiperligações!
E mesmo que não precises das hiperligações, os números de problemas aparecerão como uma coluna separada na caixa de diálogo registo, tornando mais fácil encontrar as alterações que estão relacionadas com um assunto em particular.
Algumas propriedades tsvn: requerem um valor true/false. O TortoiseSVN também entende yes como sinónimo para true e no como sinonimo para false.
Configurar Propriedades em Pastas
Essas propriedades devem ser colocadas em pastas para o sistema funcionar. Quando submetes um ficheiro ou pasta, as propriedades são lidas dessa pasta. Se as propriedades não forem aí encontradas, o TortoiseSVN irá pesquisar ascendentemente na árvore de pastas de modo ás encontrar até encontrar uma pasta não versionada, ou a raiz da árvore (eg. C:\). Se tens a certeza que cada utilizador só efectua checkout a partir do e.g. trunk/, e não de alguma subpasta, é suficiente configurar as propriedades na pasta trunk/. Se não tens a certeza, deverás configurar as propriedades em cada subpasta, recursivamente. Uma propriedade configurada mais profundamente na hierarquia do projecto, irá se sobrepor à configuração de níveis superiores (mais perto do trunk/).
As of version 1.8, TortoiseSVN and Subversion use so called inherited properties, which means a property that is set on a folder is automatically also implicitly set on all subfolders. So there's no need to set the properties on all folders anymore but only on the root folder.
Só para propriedades de projecto, i.e. tsvn:, bugtraq: e webviewer: podes usar a caixa de verificação Recursiva para fixar a propriedade em todas as subpastas na hierarquia, sem também fixa-la em todos os ficheiros.
Quando adicionas novas subpastas a uma cópia de trabalho, usando o TortoiseSVN, quaisquer propriedades de projecto presentes na pasta pai serão automaticamente adicionadas à nova pasta filho também.
Não existe informação do Controlador de Assuntos no Navegador de Repositório
Because the issue tracker integration depends upon accessing Subversion properties, you will only see the results when using a checked out working copy. Fetching properties remotely is a slow operation, so you will not see this feature in action from the repo browser unless you started the repo browser from your working copy. If you started the repo browser by entering the URL of the repository you won't see this feature.
Pela mesma razão, as propriedades de projecto não serão propagadas automaticamente quando uma pasta filho é adicionada usando o navegador de repositório.
This issue tracker integration is not restricted to TortoiseSVN; it can be used with any Subversion client. For more information, read the full Issue Tracker Integration Specification in the TortoiseSVN source repository. (“Licença” explains how to access the repository.)
A secção anterior ocupa-se com a adição da informação do problema nas mensagens de registo. Mas se tu precisares de obter informações do teu gestor de problemas? A caixa de diálogo submeter tem um interface COM que permite a integração com um programa externo, que consegue comunicar com o teu gestor. Tipicamente tu poderás querer consultar o gestor para obter a lista de problemas abertos atribuídos a ti, de modo a que possas seleccionar os problemas que estarão a ser tratados nesta submissão.
Any such interface is of course highly specific to your issue tracker system, so we cannot provide this part, and describing how to create such a program is beyond the scope of this manual. The interface definition and sample plugins in C# and C++/ATL can be obtained from the contrib folder in the TortoiseSVN repository. (“Licença” explains how to access the repository.) A summary of the API is also given in Capítulo 7, Interface IBugtraqProvider. Another (working) example plugin in C# is Gurtle which implements the required COM interface to interact with the Google Code issue tracker.
Para efeitos de demonstração, vamos supor que o teu administrador de sistemas providenciou-te um plugin de gestor de problemas que tu instalaste, e entretanto configuraste algumas das tuas cópias de trabalho para usar o plugin, na caixa de diálogo de preferências do TortoiseSVN. Quando abres a caixa de diálogo Submeter a partir de uma cópia de trabalho para a qual o plugin foi atribuído, verás um novo botão no topo da caixa de diálogo.
Neste exemplo tu podes seleccionar um ou mais problemas abertos. O plugin pode então gerar um texto, especialmente formatado, que adicionará à tua mensagem de registo.