| Ferramentas | Começando |
Utilizando o CVS
A documentação do PHP é mantida usando o sistema CVS(Sistema de Versões Concorrentes). Este sistema permite que os tradutores possam fazer mudanças em arquivos diferentes sem que um interfira no trabalho do outro.
Este sistema CVS é baseado em um servidor central que contém toda a documentação, separada por módulos. Para acessar esta documentação você precisará de um cliente e de uma conta, a qual permitirá que você envie para o servidor as suas modificações, embora você também possa acessar os arquivos como usuário anônimo, mas não terá permissão para modificar o conteúdo no servidor.
Esta seção não tem a intenção de ser um tutorial sobre o cvs, mas cobrir o necessário para se participar da tradução do manual. Caso você tenha conhecimento de cvs e queira contribuir com a melhoria dsta seção eu ficaria grato, assim como no caso de conhecer algum bom tutorial sobre cvs, nos indique e será colocado aqui o endereço. Uma ajuda basica esta em digitar em um terminal man cvs ou cvs --help.
A utlização do CVS costuma ser a maior dificuldade para as pessoas participarem da tradução e muitas acabam desistindo por causa disso, mas não deixe que isso se torne um problema. Caso não saibas ou não queira usar o CVS, pode-se fazer como outros grupos de tradução fazem, onde alguns usam e outros não. Aqueles que não usam recebem e enviam os arquivos traduzidos por email de uma pessoa que use o CVS, e esta pessoa então coloca os arquivos no servidor CVS.
Existem também otimas ferramentas graficas que facilitam muito o uso do CVS, no Windows temos o TortoiseCVS e WinCVS. No Linux existe o Cervisia.
Dos comandos do CVS, você pode usar todos que não façam modificações mesmo que você não tenha conta, isto é de forma anônima. Então o único que não irá funcionar é o "commit".
Obtendo uma conta de CVS
Antes que você possa fazer alguma modificação na documentação, você precisará ter permissão de escrita no cvs.php.net. Você sempre pode copiar os arquivos de modo anônimo, mas não pode enviar as modificações que tiver feito sem uma conta. Se você quer apenas copiar os arquivos, de uma olhada em acesso anonimo para maiores informações.
Aqui temos uma recomendação, caso não se sinta a vontade para usar o cvs, pois deve-se ter muito cuidado pois seu uso de maneira incorreta pode trazer grandes problemas para os outros, como a geração automatica do manual parar, inclusive a versão em inglês, assim se quizer pode mandar as suas alterações por email para um dos membros que usem o cvs para fazer o commit para você, em teu nome, é claro.
Mais uma recomendação, temos caso de algumas pessoas que tiveram uma conta cvs, começaram a traduzir alguma parte e pararam sem mandar arquivos, então uma recomendação, não, um pedido, pegue para traduzir uma pasta, depois dela pronta é que peça uma conta do servidor cvs, enquanto isso poderá mandar os arquivos por email para que outro faça o commit por ti, apenas para que experimente como funciona o processo de tradução e decidir se queres participar mesmo sem se envolver mais a sério antes.
Obter uma conta não é muito fácil, mas também não chega a ser difícil, você precisa fazer duas coisas.
Vá em http://www.php.net/cvs-php.php e prencha a requisição formal para a conta.
Envie um email para "group em php.net"(em inglês). Explique exatamente para que você quer a conta assim como dê algumas informações sobre você mesmo para que eles tenham uma idéia de quem você é.
Note que este processo não é automatico e que as vezes é muito demorado. Você também deverá mandar uma mensagem para a nossa lista de discussão avisando-nos de sua vontade. Quando você tiver arquivos prontos para mandar, você deverá mandar estes arquivos por email para um membro do grupo que os enviará para o cvs por você, após isso nós solicitaremos ao pessoal do php.net que libere a conta de cvs para você. A prática nos indicou que este é o melhor sistema para nos organizarmos, além do que a conta de cvs funciona como uma espécie de "premio" para aqueles que realmente colaborarem.
Fazendo o Login(cvs login)
Agora você poderá fazer alguns configurações que vão deixar a sua vida um pouco mais fácil. Estas modificações farão com que o cvs transfira os arquivos de forma compactada(tornando as operações com o servidor muito mais rapidas para quem conexão lenta com a internet) e que ele não crie diretórios que estajam vazios, você deverá modificar o seu arquivo .cvsrc.
Se você não tiver um arquivo .cvsrc em seu diretório home você deve criar um e adicione as seguintes linhas a ele. Note que se você usar o Cygwin, seu diretório home é o que abre primeiro. Esta dentro de home/nomedousuario no diretório que você instalou o Cygwin.
cvs -z3 update -d -P checkout -P diff -u
Quando você usa os comandos "login" e "checkout" do cvs, você tem que especificar o diretório raiz do servidor, algo como isto:
$ cvs -d :pserver:username@cvs.php.net:/repository
Ao invés de dizer ao cvs onde esta o repositório a cada vez que você usa, você pode especificar o repositório na sua variável de ambiente CVSROOT. Adicione em seu .bashrc ou .profile.
CVSROOT=:pserver:nomedeusuario@cvs.php.net:/repository export CVSROOT
Note que esta variável de ambiênte só estará disponível na proxima vez que você fizer o login. Também não esqueça de substituir nomedeusuario pelo seu nome de usuário, aquele que foi dado para você quando lhe deram a conta de cvs.
Agora que você já configurou tudo chegou a hora de fazer o login no repositório:
$ cvs login
Ou se você não estabeleceu o variável CVSROOT:
$ cvs -d :pserver:nomedeusuario@cvs.php.net:/repository login
Mude nomedeusuario por seu próprio nome de usuário. Será solicitada a sua senha, que será guardada em um arquivo chamado .cvspass em seu diretório home, permitindo que você utiize outras vezes o cvs sem precisar logar de novo. Caso queira remover isto você poderá apagar o arquivo ou usar o cvs logout.
Checkout
Este comando serve para se obter uma cópia dos arquivos do cvs, assim você tem os arquivos em seu computador para começar a trabalhar neles. Este comando irá criar um diretorio (no nosso caso, phpdoc-pt_BR) e colocar todos os arquivos dentro necessários para a tradução dentro dele.
É recomendado que este diretório esteja em um local que não tenha nada de mais extravagante em seu nome, como espaço ou acentuação, que podem causar futuros problemas com algumas ferramentas utilizadas. Sugestão, crie um diretório com o nome de phpdoc dentro do seu home (por exemplo: /home/fernando/phpdoc) ou dentro do seu drive c: (por exemplo: c:\phpdoc).
Após criar o diretório use o comando cd e entre nele, e após:
cvs checkout phpdoc-pt_BR
Importante: se for trabalhar com outro manual que nao seja o do php, use no lugar de phpdoc-pt_BR, smarty para o manual do Smarty, php-gtk-doc para o manual do PHP-Gtk2 e peardoc para o manual do PEAR.
Após algum tempo você terá um vários arquivos, sendo que estes arquivos são todo o manual em inglês, todo o manual em Português e tudo o que é necessário para que se compile o manual em seu próprio computador.(isto é um pouco diferente se você pegou um dos outros manuais).
Isto será necessário apenas na primeira vez, depois você poderá apenas atualizar(update) estes arquivos, não sendo necessária a copia de todos os arquivos.
Commit
Esta é um dos momentos mais importantes e onde costumam acontecer mais erros, a hora de enviar as suas modificações para o servidor cvs.
Caso esteja querendo mandar uma nova tradução, deve usar o comando add antes e só depois fazer o commit.
É pedido que antes de enviar os seus arquivos você gere o manual em seu proprio computador, para que se tenha certeza que não há nenhum problema, e que a compilação automatica do manual não seja interompida.
MUITO IMPORTANTE: tenha cuidado antes de enviar para ter certeza que você enviará os arquivos para o local certo, e não para substituir os originais em inglês. Todos os nossos arquivos devem estar dentro do diretório pt_BR, e salvo em condições muito especiais não se muda nada que esteja fora dele.
Você deverá colocar uma pequena mensagem indicando qual foi a modificação que foi realizada ou se é uma nova tradução, sendo que esta mensagem deverá estar em inglês para que as pessoas do original também possam acompanhar o progresso da nossa tradução.
Exemplo de como mandar um arquivo:
cvs commit -m "New Translation" arquivo1
Você pode por exemplo especificar vários arquivos de uma vez, mas peço que faça apenas um de cada vez pois fica mais facil para acompanhar o que foi feito, já que a cada vez que se faz um commit uma mensagem é posta na lista de discussão doc-pt-br@lists.php.net, contendo esta descrição, assim como as modificações que foram feitas.
Update
É sempre uma boa ideía atualizar a sua copia do manual de vez em quando, de preferência sempre antes que você for fazer alguma modificação, assim você pode ter certeza de estar trabalhando com as versões mais novas dos arquivos. Para fazer isto você precisa apenas entrar no diretório onde esta a sua documentação(se seguiu as sugestões até aqui, esta em seu diretorio home, no mesmo exemplo, /home/fernando/phpdoc/phpdoc-pt_BR), este será o diretorio que foi criado com o cvs checkout.
cvs update
Se você quizer atualizar apenas algum arquivo pode usar o seu nome logo após o update, por exemplo:
cvs update arquivo1 arquivo2
Add
Quando se traduz um arquivo novo é necessário que ele seja adicionado ao repositório, assim como as vezes se necessita adicionar diretórios, para isso se usa o comando add, assim:
cvs add arquivo1
Isto irá apenas adicionar o arquivo ao cvs localmente, após você terá que usar o commit para tornar esta adição disponível a todos.
Remove
Serve para que um arquivo seja removido do cvs. Já que o cvs guarda toda a historia dos arquivos, este não é um passo irreversível, mas tenha cuidado que alguns arquivos são necessários para a geração automatica do manual. Eu não creio que vá existir a necessidade de se excluir algum arquivo, salvo no caso de algum arquivo seja excluído também em Inglês.
Você deverá primeiro excluir o arquivo no seu diretório, para depois poder usar este comando.
cvs remove arquivo1
Após você remove-lo é necessário utilizar o commit.
Status
Você fez as suas modificações e agora gostaria de saber quais arquivos foram modificados, você pode pedir ao cvs para que ele lhe diga qual é a situação do arquivo ou arquivos.
cvs status -l
Mostra o estado de todos os arquivos no diretório atual, o que pode ser uma grande lista que irá passar rapidamente pela tela, então você pode usar o less para ver melhor:
cvs status -l | less
Ou limitar a saida a apenas alguns arquivos, incluindo os seus nomes:
cvs status arquivo1 arquivo2
| Ferramentas | Começando |
| Indice | |