Padrões em Web Development

Este documento aborda os Padrões (best-practices) em Desenvolvimento de soluções online que a DoWeDo-IT aplica aos processos de codificação das doSolutions. Edite-o apenas quando possa contribuir muito significativamente para a melhoria e correcção do seu conteúdo. Caso pretenda somente discutir acerca do seu conteúdo, usa o documento de discussão correspondente.

A DoWeDo-IT usa diversos repositórios Subversion para gerir as várias revisões ao código-fonte de cada uma das soluções FOSS com que trabalha.

Cada repositório começa com a importação de uma estrutura hierárquica de pastas que serão mais tarde usadas nos processos de controlo de versões:

• clients/ - esta pasta irá conter todas as instalações em clientes que usam a solução gerida no repositório. É uma falha de segurança caso seja preciso transferir dumps do repositório entre colaboradores.
• libraries/ - esta pasta irá conter todas as libraries externas à solução gerida no repositório que são necessárias ao correcto funcionamento da solução.
• migrations/ - esta pasta irá conter todas as migrações da solução gerida no repositório. Uma migração é uma ramificação da solução com o propósito de corrigir (manutenção correctiva) ou extender (manutenção evolutiva) certas e determinadas funcionalidades.
• releases/ - esta pasta irá conter todas as versões da solução gerida no repositório que são disponibilizadas aos clientes.
• sources/ - esta pasta irá conter o código-fonte principal e estável da solução gerida no repositório.
• vendors/ - esta pasta irá conter as sucessivas versões da solução base da solução gerida no repositório. Normalmente, cada doSolution tem por base uma reconhecida solução à qual extende e corrige certas e determinadas funcionalidades, a fim de adequar a solução base ao mercado Português.

Existem 3 pastas de topo, que estão directamente relacionadas com a gestão de revisões das soluções:

• doClients/ - esta pasta contém todos os sites implantados pela DoWeDo-IT nos clientes. Cada site corresponde à aplicação de uma ou mais soluções FOSS num ou mais sub-domains do cliente.
• doSolutions/ - esta pasta contém todas as soluções integradas ou desenvolvidas pela DoWeDo-IT.
• doVendors/ - esta pasta contém todas as soluções FOSS externas à DoWeDo-IT que estão implantadas em um ou mais clientes ou então que são a base de uma ou mais soluções doSolutions.

Cada pasta está associada a um conjunto de repositório, independentes entre si:

• Cada doClient/«site»/ está associado a um repositório exclusivo, dentro da pasta doClients/ na hierarquia de repositórios.
• Cada doSolutions/«doSolution»/ está associada a um repositório exclusivo, dentro da pasta doSolutions/ na hierarquia de repositórios.
• Cada doVendors/«solution»/ está associada a um repositório exclusivo, dentro da pasta doSolutions/ na hierarquia de repositórios.

As pastas de topo doSolutions/ e doVendors/ partilham o mesmo repositório, que corresponde à pasta doSolutions/«doSolution»/. Isto simplifica os processos de merging sempre que sai uma nova versão da solução base da doSolution correspondente. Por sua vez, as sub-pastas doSolutions/«doSolution»/ e doVendors/«solution»/ apresentam todas a mesma estrutura hierárquica:

• migrations/ - esta pasta contém todas as migrações em desenvolvimento relacionadas com a solução ou site do cliente.
• pristine/ - esta pasta é uma cópia exacta do código-fonte em produção. É útil somente para comparar o código-fonte que está em produção (versão estável mais recente) com o código-fonte que se encontra na pasta sources/ do repositório da doSolution.
• sources/ - esta pasta é usada para efectuar actualizações ao código-fonte principal e estável, que se encontra numa pasta do repositório da solução correspondente. Essa pasta no respositório será a pasta migrations/«migração» ou a pasta vendors/«solução». A primeira é usada exclusivamente com migrações da doSolution em questão, enquanto que a segunda é usada exclusivamente com novas revisões à solução base da doSolution.

Os procedimentos afectam as pastas das seguintes formas:

• Import - este procedimento lê o código-fonte da versão inicial da solução a partir de um destas pastas:
  • doClients/migrations/«solução»/ - que corresponde à versão inicial a importar para o repositório da solução implementada no sub-domain correspondente do serviço de alojamento do cliente. Esta importação será efectuada para a sub-pasta clients/«cliente»/«sub-domain»/ do repositório da doSolution.
  • doSolution/migrations/«v0.0.0»/ - que corresponde à versão inicial a importar para o tronco principal no repositório da doSolution. Esta importação será efectuada para a sub-pasta sources/ do repositório da doSolution.
  • doVendors/migrations/«v0.0.0.»/ - que corresponde à versão inicial a importar para sub-pasta vendors/«solução» do repositório da doSolution que é baseada nesta solução.
• Commit - este procedimento lê o código-fonte actualizado numa destas pastas:
  • doClients/«sub-domain»/ - que corresponde à versão em produção no sub-domain correspondente do serviço de alojamento do cliente. Esta actualização será efectuada para a sub-pasta clients/«cliente»/«sub-domain»/ do repositório da doSolution.
  • doSolution/«sources»/ - que corresponde à versão estável mais recente que é necessário actualizar para o tronco principal no repositório da doSolution. Esta actualização será efectuada para a sub-pasta sources/ do repositório da doSolution.
  • doVendors/«sources»/ - que corresponde à versão mais recente e actual (mesmo não sendo a mais estável) da solução base da doSolution. Esta actualização será efectuada para sub-pasta vendors/«solução» do repositório da doSolution.
• Export - este procedimento exporta o código-fonte actualizado para uma destas pastas:
  • doClients/«sub-domain»/ - que corresponde à versão em produção no sub-domain correspondente do serviço de alojamento do cliente. Esta exportação é sempre feita a partir da sub-pasta clients/«cliente»/«sub-domain»/ do repositório da doSolution.
  • doSolution/«pristine»/ - que corresponde à versão estável mais recente que é necessário actualizar para o tronco principal no repositório da doSolution. Esta exportação é sempre feita a partir da sub-pasta sources/ do repositório da doSolution.
  • doVendors/«pristine»/ - que corresponde à versão mais recente e actual (mesmo não sendo a mais estável) da solução base da doSolution. Esta exportação é sempre feita a partir da sub-pasta vendors/«solução» do repositório da doSolution.
• Checkout - este procedimento coloca uma cópia de trabalho do código-fonte para uma destas pastas:
  • doSolution/migrations/«migração»/ - que corresponde à preparação da ramificação do código-fonte estável, na sub-pasta sources/ do repositório da doSolution, para um novo trabalho de migração. Após o checkout concluir, é obrigatório efectuar-se primeiro o branching da cópia de trabalho para uma sub-pasta migrations/«migração» do repositório da doSolution e depois o switching da cópia de trabalho para esta nova ramificação.
  • doSolution/«sources»/ - somente nos casos em que esta pasta foi acidentalmente removida. O checkout é feito sempre a partir da sub-pasta sources/ do repositório da doSolution.
  • doVendors/«sources»/ - somente nos casos em que esta pasta foi acidentalmente removida. O checkout é feito sempre a partir da sub-pasta vendors/«solução»/ do repositório da doSolution.
• Merge - este procedimento consolida as alterações entre migrações e versão estável através de uma destas pastas:
  • doSolution/migrations/«migração»/ - esta cópia de trabalho, sincronizada com a ramificação migrations/«migração» do repositório, é usada para consolidar as alterações ao código-fonte com a versão estável existente na pasta sources/ do repositório da doSolution. Este procedimento é executado somente quando a migração termina com sucesso, sendo o passo seguinte a remoção da sub-pasta migrations/«migração» do repositório.

Dentro da pasta migrations/, exterior ao repositório Subversion, é prático usar este comando Shell:

  for d in `ls -dAF  * | grep "/" | sed s:/::`; do cd $d ; find . -type f > ../$d.lst; cd ..; done

Este comando tem como resultado o output de ficheiros que têm como conteúdo a lista de todos os ficheiros correspondentes à versão da solução existentes na sub-pasta respectiva. Estas listas podem depois, através de ferramentas idênticas ao WinMerge, serem comparadas entre si a fim de se identificar de forma rápida e prática quais os ficheiros que são para remover de uma versão anterior para uma versão posterior.

O seu funcionamento explica-se forma breve:

• O comando ls encontra todas as entradas, mesmo escondidas por causa de ter activo o argumento -A, somente da pasta actual onde o comando é executado, porque está restrito com o argumento -d. O argumento -F é útil para formatar de forma distinta a apresentação das entradas que são pastas das que são ficheiros.
• O comando grep filtra todas as entradas para retornar somente as que são pastas, graças ao filtro “/”.
• O comando sed remove o caractér de formatação que indica que as entradas são pastas da lista a retornar ao ciclo. Isto é importante porque o nome da entrada será usado mais à frente para nomear o ficheiro com o conteúdo de cada pasta.
• O comando for vai executar para cada entrada retornada (sub-pastas da pasta corrente) o comando que:
  • Muda temporariamente para a sub-pasta actual no ciclo.
  • Lista todos os ficheiros dessa mesma sub-pasta. O comando find é usado com o argumento -type f para que a listagem se restringa a ficheiros e exclua as pastas da sub-pasta actual.
  • Retorna à pasta corrente antes de passar à próxima iteração.

NOTA: É preciso mudar temporariamente para a sub-pasta do ciclo para que o ficheiro com o conteúdo de cada sub-pasta, que deve corresponder a uma e uma só versão da solução, não contenha o seu próprio nome. Porque senão, a comparação de todas as linhas daria diferenças, já que duas versões têm obrigatoriamente representações diferentes.