CVS para programadores

Desenvolvimento: CVS para programadores

CVS são as iniciais de Concurrent Versioning System, uma forma de trabalho habitualmente utilizada para grandes projectos de software. No CVS estão integradas todas as versões de todos os ficheiros para que nada seja perdido e a sua utilização pelos vários utilizadores seja registada. Este sistema permite também a combinação do código criado por duas ou mais pessoas que trabalhem simultaneamente sobre o mesmo ficheiro. Todo o código e respectivas versões são armazenados num servidor central (no caso do Moodle, em cvs.moodle.org). Para mais informações sobre CVS, poderá consultar o livro on-line "Open Source Development with CVS"..

Entrar no projecto como programador

Se obteve permissões de escrita no CVS para ajudar a desenvolver e manter o Moodle! Bem-vindo a bordo! Para obter estas permissões para escrever ou editar no Moodle's CVS archive, primeiro deverá ter uma conta no servidor. Só programadores de confiança conseguem estas contas. Para conseguir o acesso, deverá procurar o link "Apply for CVS Access" na página CVS do Moodle.org (http://moodle.org/cvs), comunicar quais os módulos aos quais deseja ter acesso (por exemplo: modulo de idioma) e porquê. A resposta será dada em menos de um dia. Concluída esta fase, já deverá possuir todas as permissões de que necessita, necessitando apenas de configurar a sua máquina e descarregar o código fonte corrente, podendo logo de seguida começar a trabalhar nele. Para os exemplos que veremos mais à frente vamos assumir que o nosso nome de utilizador é myusername a nossa password é mypassword.

Módulos CVS

Dentro do CVS, a palavra “módulo” refere-se a conjuntos separados de código. Nos arquivos do Moodle existem os seguintes módulos: • moodle – o código fonte principal do Moodle • lang – todos os packs de idiomas • contrib – contribuições de utilizadores e todo o tipo de código em desenvolvimento. • mysql – um phpMyAdmin para trabalhar com a base de dados do Moodle. • windows-cron - um pequeno pacote que possibilita o funcionamento do ?cron? nos sistemas Windows. • docs – diversas contribuições de utilizadores para documentação.

A maioria das pessoas está a trabalhar nas funcionalidades existentes no módulo moodle, mas muitas estão também contribuindo com novas ideias para o módulo contrib. Uma vez alcançado um certo nível de “maturidade” no código da área contrib, este pode ser migrado para a área principal da área moodle.

Comandos CVS básicos

CVS em Unix O CVS do Moodle utilize ssh como camada de transporte para segurança, pelo que deverá ter a variável de ambiente CVS_RSH na sua Shell Unix. E aconselhável por estes comandos nos seus arquivos .bashrc ou .chrc para não ter de os digitar repetidamente:

      setenv CVS_RSH ssh (para csh, tcsh etc)
      export CVS_RSH=ssh (para sh, bash etc)

Seguidamente, poderá obter a última versão do Moodle utilizando este comando (todo na mesma linha). NOTA: Não tente correr este primeiro comando CVS sobre uma instalação do Moodle já existente: Inicie novamente com uma nova directoria:

      cvs -z3 -d:ext:myusername@cvs.moodle.org:/cvsroot/moodle co moodle

Para outros módulos CVS, os comandos são semelhantes:

      cvs -z3 -d:ext:myusername@cvs.moodle.org:/cvsroot/moodle co contrib

Se desejar obter simplesmente um plugin (no exemplo é o bloco “attendance”) existente em contrib dentro da directoria actual, pode usar:

      cvs -z3 -d:ext:myusername@cvs.moodle.org:/cvsroot/moodle co -d attendance contrib/plugins/blocks/attendance

Cada vez que se executa um comando é pedida a password, poderá no entanto configurar as chaves autorizadas de forma a contornar esta situação. Deverá agora ter uma nova directoria ‘moodle’, podendo alterar o seu nome ou localização. Entre em:

      cd moodle

Todos os ficheiros do Moodle devem estar nesta localização, possibilitando localmente (na cópia instalada) a alteração dos mesmos. Para comparar os seus ficheiros com os da cópia principal do CVS no servidor poderá utilizar os comandos cvs diff, por exemplo:

      cvs diff -c config-dist.php
      cvs diff -c lang

Para obter as ultimas actualizações a partir do servidor:

      cvs update -dP

Para copiar os seus novos ficheiros de volta para o servidor necessitará de algo como:

      cd lang/ca
      cvs commit

Ser-lhe-á pedido que adicione alguns comentários (dependendo do seu editor de texto predefinido). Deverá escrever comentários descritivos e com significado. Depois disto as suas alterações serão enviadas para o servidor CVS e guardadas no respectivo repositório. Para poupar algum tempo poderá colocar argumentos predefinidos dentro de um ficheiro chamado .cvsrc na sua directoria principal. Por exemplo, o meu contém:

      diff -c
      update -dP

Poderá utilizar o 'cvs help' para mais informações ...

CVS no Mac OSX Poderá seguir as mesmas instruções descritas anteriormente para Unix numa janela terminal. No entanto o comando cvs não está instalado por defeito no OSX. Deverá instalar previamente as ferramnetas XCode. Deverá encontar as mesmas no seu disco de instalação original. Caso contrário poderá descarrega-las a partir do Web site da Apple para o desenvolvimento (http://devoloper.apple.com).

CVS em Windows Primeiro, deverá descarregar uma cópia actual do Moodle usando a sua conta de programador.

1. Descarrega TortoiseCVS a partir de tortoisecvs.org, instale e reinicie.

2. Procure ou crie uma pasta onde o Moodle possa ser descarregado.

3. Clique com o botão direito do rato na pasta e escolha “CVS Checkout”. Deverá surgir uma caixa de diálogo.

4. Copie este texto para o campo CVSROOT (utilizando o seu próprio username!):

         :ext:myusername@cvs.moodle.org:/cvsroot/moodle

5. No campo “Module”, digite “moodle” para obter a ultima versão do moodle, “contrib” para obter a directoria de contribuições ou “mysql” para obter o módulo MySQL Admin.

6. Clique em “OK” e tudo será descarregado. Uma caixa de diálogo deverá mostrar todos os ficheiros que estão a ser descarregados, depois disto já deverá ter uma cópia completa do Moodle instalada. Poderá posteriormente obter actualizações a partir do servidor CVS:

.1. Clique com o botão direito do rato na sua pasta Moodle (ou em qualquer dos seus ficheiros) e escolha “CVS Update”.

.2. Examine atentamente os registos e tome nota dos conflitos que podem ocorrer entre as alterações ao código que efectuou na sua cópia e as novas versões obtidas. Estes ficheiros terão de ser editados manualmente de forma a resolver os conflitos. Depois de modificar os ficheiros (os seus ícones mudarão de verde para vermelho), poderá enviar as alterações de volta ao servidor CVS:

.1. Clique com o botão direito do rato na sua pasta Moodle (ou em qualquer dos seus ficheiros) e escolha “CVS Commit…”.

.2. Na caixa de diálogo, digite uma descrição clara das alterações que estão a ser submetidas. Incluindo sempre o nome de qualquer edição do Tracker do Moodle relacionado com o que está a ser corrigido (MDL-XXXX).

.3. Clique em “OK”. As suas alterações serão enviadas para o servidor.

.4. Se criar uma pasta, deverá ter algum cuidado ao usar a opção “CVS add” pois irá acrescentar a pasta ao CVS sem requerer verificação/confirmação (commit) da mesma. Uma vez adicionada, a pasta não pode ser removida do CVS mesmo que esteja vazia.

NOTA: Deverá ter em atenção que (à data de edição deste texto em Abril de 2008) o TartoiseCVS 1.10.6 poderá não funcionar plenamente com o Windows Vista. Poderá reportar bugs e encontrar mais informação no site TortoiseCVS ou no Google “TortoiseCVS vista”.

Mensagens commit CVS

Por cada alteração submetida no CVS, deverá receber uma mensagem de confirmação/verificação (denominada commit), contendo o ID da edição (por exemplo, MDL-12345) e da breve descrição do problema nela corrigido. Se julgar que a breve descrição é insuficiente, poderá adicionar mais informação no Tracker do Moodle.org ou no Moodle Docs (https://docs.moodle.org).

Trabalhando com ramos

Este diagrama mostra como o módulo principal do Moodle se subdividiu e diferentes versões ao longo dos tempos.

Para ver todas as etiquetas e ramos que estão disponíveis, use este comando em qualquer dos ficheiros antigos (tal como o índex.php a directoria raiz do moodle):

Erro ao criar miniatura: Não é possível guardar a miniatura no destino

cvs status –v índex.php

Algumas directrizes de colocação de etiquetas: • O nome das etiquetas e dos ramos deve estar todo em letras maiúsculas. • As etiquetas e ramos devem ser SEMPRE aplicados ao módulo inteiro (todo o Moodle). Não etiquetar ficheiros ou directorias individuais. • Não é permitido renomear etiquetas devido aos utilizadores poderem ser induzidos em erro.

Desenvolvimento do tronco (trunk)

O tronco do CVS é a versão principal de desenvolvimento do Moodle. No CVS também conhecido como HEAD, o ramo por defeito (default branch). Os programadores do Moodle têm sempre como objectivo manter a plataforma o mais estável possível, mas com a constante introdução de pequenas porções de código, existe sempre a possibilidade da existência de pequenos erros e focos de instabilidade. Em qualquer momento podemos decidir que o produto tem funcionalidades necessárias para o lançamento de uma nova versão. Nesta altura, o troncoé marcado com uma etiqueta MOODLE_XX_BETA (com vista a poder voltar em qualquer momento a esse ponto) e um novo ramo é criado para essa versão com o nome de MOODLE_XX_STABLE.

A Beta package is also released at this point - it's for testers who don't use CVS but want to test the latest features and report bugs.

Neste momento é também publicado um pacote Beta – é para os utilizadores que não utilizam o CVS mas que querem comprovar as novas funcionalidades e ajudar na detecção de erros.

Ramos estáveis para cada versão

Assim que o ramo estável MOODLE_XX_STABLE for criado, os esforços de desenvolvimento dividir-se-ão em dois caminhos por um algum tempo. Algumas pessoas podem continuar a trabalhar em características novas no tronco para a versão seguinte, mas a maioria dos programadores devem concentrar-se em usar o ramo ESTÁVEL actual e em reparar os erros que vão surgindo na mesma. É possível comutar uma cópia local do Moodle à versão ESTÁVEL usando o seguinte comando em Unix na directoria de raiz da plataforma:

  cvs update -dP -r MOODLE_XX_STABLE

Depois disto, todos comandos descritos anteriormente serão aplicados ao ramo estável. Para voltar ao tronco, faz-se simplesmente:

  cvs update -dPA

Em clientes Windows deverá existir um menu no qual se poderá fazer a escolher do ramo. Quando o novo ramo se apresentar com uma estabilidade aceitável, uma versão poderá ser declarada. Os pacotes são criados para a distribuição o ramo será etiquetado (por Martin Dougiamas) com uma etiqueta (tag) chamado: MOODLE_XXX.

Adicionando correcções

Todas as correcções de erros da versão ESTÁVEL devem ser adicionadas ao tronco de modo que se tornem disponíveis nas versões futuras de Moodle. Uma etiqueta (Tag) flutuante chamada MOODLE_XX_MERGED deverá ser mantida de modo a manter o caminho da última fusão. O procedimento para tal fusão é como segue (neste caso o CVS está a ser usado na linha de comando de Unix mas as etapas não diferem nos outros clientes de CVS):

1. É altamente recomendado manter localmente uma cópia de segurança de cada ramo estável e da versão do tronco¬/versão principal de forma a ser fácil alternar entre elas. Ajuste-os todos como Web sites virtuais em sua máquina do desenvolvimento. Eu uso directórios como /moodle/18, /moodle/19 /moodle/dev etc.

2. Faça a actualização para a última versão estável (eu usarei XX no exemplo mas poderia ser 18, 19 etc.) para os ficheiros relevantes, execute um cvs diff apenas para se certificar do que está a ser verificado. De notar que só é necessário fazer a actualização dos ficheiros/directorias onde se está a trabalhar, mas por vezes é aconselhável fazer uma actualização total com vista a fazer uma verificação final da funcionalidade utilizando a Web.

        cd /moodle/XX/user
        cvs update -dPA
        cvs diff -c file1.php file2.php

3. Se tudo estiver correcto, fazer a . Verifique se a mensagem anexada à submissão contém (commit) o ID do tracker onde se encontra o erro corrigido (ex. MDL-1111) e uma boa descrição do raciocínio feito. Se não for especificada nenhuma mensagem na linha de comandos, aparecerá um modo de edição de modo a fazê-lo.

        cvs commit -m "MDL-1234 Corrected a small typo in the user name field" file1.php file2.php

4. Ir para a última versão do tronco e certificar-se que esta se encontra actualizada.

        cd /moodle/dev/user
        cvs update -dPA

5. Fazer a junção de tudo na cópia local do tronco do ramo estável desde a ultima junção. Pode ser usada a sequência dos passos (4) e (5) Para adicionar as alterações noutros ramos estáveis ( para afectar as alterações a outras versões estáveis anteriores).

        cvs update -kk -j MOODLE_XX_MERGED -j MOODLE_XX_STABLE file1.php file2.php

6. É aconselhável uma analise cuidada do log que resulta da actualização, para uma posterior reparação de todos os ficheiros que apresentarem conflitos. Depois , pode ajudar correr o comando diff para a certificação que o resultado é o esperado:

        cvs diff -c file1.php file2.php

7. Verificar a cópia local da versão alterada e fazer a cópia para aversão CVS do tronco

        cvs commit -m "MDL-1234 Corrected a small typo in the user name field, merged from XX" file1.php file2.php

8. Voltar á versão do ramo

        cd /moodle/XX/user

9. Actualizar a etiqueta flutuante dos ficheiros modificados ( para que haja correspondência com MOODLE_XX_STABLE) para que o processo possa ser repetido da próxima vez.

        cvs tag -RF MOODLE_XX_MERGED file1.php file2.php

Finalmente, os valores para $version em todos os ficheiros version.php Moodle dentro do ramo estável se possível não devem ser actualizados (excepto o último dígito se absolutamente necessário). A razão é que alguém que faça a actualização de uma versão muito estável à versão muito estável seguinte poderia não beneficiar dos melhoramentos da base de dados que aconteceram no tronco.

Características dos ramos para grandes alterações

Ocasionalmente, pode haver uma funcionalidade muito grande que necessite ser analizada para que muitos utilizadores possam trabalhar nela, mas sendo demasiado instável não é aconselhável incluí-la no desenvolvimento tronco principal. Nestes casos pode ser criado um ramo de curto prazo em que irá ser trabalhada essa funcionalidade, para depois a mesma ser adicionada ao tronco da versão principal o mais brevemente possível. Um exemplo deste tipo de ramo chamado MOODLE_17_WIDGET pode ser visto no diagrama acima. Se for necessário utilizar este método (widget), siga os seguintes passos:

1. Discutir a situação com outros programadores e certificar se esta opção será mesmo necessária.

2. Fazer uma etiqueta no tronco (de todo o moodle) com o nome de MOODLE_XX_WIDGET_PRE

        cvs tag -R MOODLE_XX_WIDGET_PRE

3. Criar um ramo próprio chamado MOODLE_XX_WIDGET

        cvs tag -Rb MOODLE_XX_WIDGET

4. Trabalhar esse ramo até que seja atingido um nível aceitável de estabilidade. Fazer a submissão (commit).

        cvs commit

5. Quando o trabalho estiver finalizado, adicionar o ramo inteiro ao tronco, reparar conflitos, submeter para o tronco e depois abandonar o ramo.

        cvs update -dPA
        cvs update -kk -j MOODLE_XX_WIDGET
        cvs commit