Discussão

Este documento serve como registro histórico da discussão sobre os assuntos do documento acerca de um Ambiente de Desenvolvimento genérico.

Se quiser somente deixar as suas sugestões ou comentários, por favor faça-o na Caixa de Sugestões deste SiteWiki. Obrigado.

Best-Practices

Esta secção apresenta a lista de procedimentos que devem ser seguidos, dependendo da tarefa em questão:

No caso de um processo de codificação (manutenção correctiva ou evolutiva) é importante dominar os procedimentos de controlo de versões, bem como da gestão de incidentes;
No caso da resolução de incidentes (somente com testes) é necessário dominar os procedimentos da gestão de incidentes, bem como da documentação técnica e de utilizador;
Caso uma nova versão fique pronta para entrar em Produção, é obrigatório seguir os procedimentos de release de versões.

Controlo de Versões

:?: Pode-se receber notificações de alterações?

Sim. Através do acesso ao canal RSS disponibilizado pelo WebSVN, pode-se receber as notificações sobre manutenções correctivas (bugs ou issues) ou manutenções evolutivas (feature requests) que estão concluídas. É suficiente aceder ao canal RSS da pasta trunk/, onde são comitted todas as alterações oficiais ao projecto.

:?: Pode-se receber notificações de novas versões?

Sim. Através do acesso ao canal RSS disponibilizado pelo WebSVN, pode-se receber as notificações sobre mais nova release que é completada. As releases são committed da pasta trunk/ do projecto para a pasta releases/, pelo que é suficiente aceder ao canal RSS da pasta releases/ em vez de todo o projecto.

:?: Como proceder para iniciar um novo processo de codificação?

É preciso realizar a ramificação da pasta trunk/ para uma nova sub-pasta da pasta issues/. Esta nova sub-pasta será usada durante toda a duração do processo de codificação (manutenção evolutiva ou correctiva).

:?: Como prosseguir com um processo de codificação?

Enquanto o ramo estiver aberto, pode-se em qualquer altura fazer commits e checkouts, sem restrições. É somente preciso garantir que alterações destinadas a serem “fundidas” com o código da pasta trunk/ sejam documentadas e testadas convenientemente.

:?: O que fazer para terminar um processo de codificação?

É preciso “fundir” as alterações efectuadas com sucesso, após os testes necessários (e documentados) com o código do trunk/. Se não houver conflitos, então deve-se remover a sub-pasta criada na pasta issues/ para o processo de codificação que agora termina. Se houver conflitos, é preciso resolver as alterações entre ramos, antes de se remover as sub-pastas respectivas. Atenção: o código da pasta trunk/ tem que permanecer sempre estável, mesmo que não contenha todas as funcionalidades mais recentes existentes em alguns ramos.

:?: Como estar a par dos processos de codificação em curso?

Basta aceder ao canal RSS disponibilizado pelo WebSVN, para se receber as notificações sobre as alterações relativas a incidentes, existentes nos diversos ramos da pasta issues/. Quando um processo de codificação terminar, as suas alterações são “fundidas” com o código da pasta trunk/ e a sub-pasta será removida da pasta issues/. Apenas developers poderão ter interesse em manter-se a par dos diversos processos de codificação em curso. Os restantes interessados deverão aceder aos canais RSS das pastas trunk/ e releases/.

:?: Deve-se reportar o processo de codificação num incidente?

Sim. Há incidentes correctivos (bugs ou issues) e incidentes evolutivos (feature requests). Qualquer processo de codificação é despoletado por uma destas acções, e por isso é obrigatório ter um número de incidente associado bem como estar devidamente documentado.

:?: Quais as regras e convenções para documentar um processo de codificação?

Um processo de codificação é sempre despoletado por um incidente. Deve por isso estar documentado no sistema de gestão de incidentes. A documentação que é preciso existir no âmbito do controlo de versões prende-se somente com comentários embedidos no código-fonte e nas mensagens de commit das alterações.
:: FIXME → documentar best-practices para comments e commits. ::

Gestão de Incidentes

Receber notificações de incidentes: ?
Abrir um novo incidente: ?
Actualizar um incidente: ?
Fechar um incidente: ?
Documentar o incidente: ?

Release de Versões

Preparar o pacote para migração? Nota: Como preparar o pacote de migração, somente com as alterações (modificações, adições e remoções) à versão anterior? O phpBB disponibiliza o pacote integral, o pacote de upgrade e as diferenças entre versões. Como se pode efectuar este procedimento?
Notificar o começo da migração de uma nova versão?
Notificar a conclusão da migração da nova versão?

:?: É obrigatório documentar a migração?

Sempre. É importante documentar-se os procedimentos de instalação, de configuração / optimização e de actualização (upgrade). A migração corresponde a uma nova release, que engloba o código das alterações realizadas em conjunto com os pacotes criados (integrais e upgrade) e juntamente com o CHANGELOG. Este ficheiro reporta o histório das alterações, indicando o número de incidente resolvido seguido de uma breve e sucinta descrição da alteração efectuada.

Discussão

:?: Como ligar documentos do SiteWiki ao sistema de controlo de versões?

É importante para relacionar aspectos técnicos que fiquem documentados no SiteWiki às versões em questão.

:?: Como ligar documentos do SiteWiki ao sistema de gestão de incidentes?

Em vez de se preencher, normalmente de forma confusa, o histórico do incidente com informação a mais (conotada por “desinformação”) é importante ter uma forma de ligar o histórico do incidente à documentação técnica acerca da sua resolução. A maioria das pessoas que acede ao sistema de gestão de incidentes procura apenas a descrição do incidente e o seu estado actual. Os tecnicismos inerentes à sua resolução são normalmente mais do que a maioria das pessoas espera encontrar no histórico do incidente. Mas, é também importante registrar a evolução técnica da sua resolução, quer através das alterações ao código-fonte (versões) quer através dos testes efectuadas para se concluir sobre a resolução do incidente.

:?: Como ligar o histórico de um incidente ao sistema de controlo de versões?

É importante para saber qual a versão que resovleu um incidente, bem como saber que a versão a.b.c.d resolveu os incidentes #NNN, #…, e #MMM.

:?: Como ligar o histórico de um incidente a documentos no SiteWiki?

É importante para saber tudo sobre um incidente, sem que a informação esteja confusa e toda misturada num só local. Poderá também ser a melhor forma de relacionar um incidente com uma versão e vice-versa.

:?: Como ligar o log de um commit no controlo de versões a documentos no SiteWiki?

:?: Como ligar o log de um commit no controlo de versões aos incidentes?

:?: Quais as possibilidade de reportar um incidente?

Um incidente deve ser reportado:

Através do acesso via Web;
Por mensagens de correio electrónico (e-mail).

:?: Quais as possibilidades de notificação de incidentes?

A actualização de um incidente pode ser notificada:

Através do canal RSS, periodicamente;
Através da subscrição de mensagens de correio electrónico, automaticamente geradas pelo sistema;
Através da monitorização de incidentes, reportados em mensagens de correio electrónico, automaticamente geradas pelo sistema.