Skip to content

Roteiro Git

Jump to bottom
alfsb edited this page Feb 7, 2021 · 10 revisions

Introdução

Este roteiro é destinado àqueles que querem contribuir com o manual do PHP utilizando o git em linha de comando. É especificamente destinado que preferem esse ambiente em particular, mas também àqueles que ainda não possuem credenciais PHP.net, mas que pretendem se tornar tradutores permanentes do manual.

Para contribuições esporádicas ou sem instalação de ferramentas veja o roteiro de como realizar contribuições pela interface web do GitHub.

Procedimento geral

Para contribuir com o manual são quatro passos, assim resumidos:

  1. Baixar ou atualizar os arquivos fontes;
  2. Traduzir ou sincronizar uma tradução;
  3. Validar a consistência do manual;
  4. Commit, push e pull request.

Embora seja possível utilizar ambientes Windows e outros para traduzir o manual, o ambiente explicado aqui é um Linux (especificamente Debian/Ubuntu), dada a facilidade de instalação (ou virtualização) dessa distribuição em particular.

Passo Zero: Fork e obtendo os fontes

Os fontes oficiais são gerenciados num repositório git oficial e alguns repositórios GitHub espelhos. Autores e tradutores com credenciais podem operar contra o repositório oficinal diretamente. Para utilizar esse roteiro sem uma credencial (o mais comum), é preciso ir no repositório espelho doc-pt_br e realizar um fork.

É necessário também que o git em linha de comando esteja instalado no computador. Num terminal, verifique a instalação:

git --version

Caso não esteja instalado, execute:

sudo apt-get install git

Depois é preciso baixar os fontes uma única vez. Para tanto, execute:

# Configurações iniciais

GITHUB_FORK_USERNAME=seu.login.github.aqui
mkdir phpdoc
cd phpdoc

# Primeira baixa de arquivos

git clone git@git.php.net:/doc/base.git
git clone git@git.php.net:/doc/en.git
git clone https://github.com/$GITHUB_FORK_USERNAME/doc-pt_br pt_BR

# Configurando o espelho como uma fonte de atualizações

cd pt_BR

git remote add upstream https://github.com/php/doc-pt_br
git fetch upstream
git checkout master
git merge upstream/master

cd ..
cd ..

Isso irá criar uma pasta phpdoc no mesmo diretório que os comandos forem executados. Toda a tradução acontecerá aqui. Para entrar na pasta e ver o seu conteúdo:

cd phpdoc
ls

Haverá três diretórios aqui:

  • base: Contém scritps e outros arquivos necessários a compilação do manual.
  • en: Contém os originais do manual, em inglês.
  • pt_BR: Contém as traduções do manual, especificamente a tradução para português do Brasil.

Você somente vai mexer com arquivos dentro de pt_BR. Para ver se tudo deu certo, faça um (cd pt_BR; git status), qual deve retornar algo como:

No ramo master
nada a submeter, diretório de trabalho vazio

Apesar da mensagem "vazio", isso é sinal que deu tudo certo. Os passos acima serão feitos uma única vez. O precedimento normal é uma repetição dos passos seguintes.

Passo 1: Atualizando os fontes

Para trabalhar a partir dos fontes mais atuais possíveis, sempre comece o dia com a sequência a partir do seu diretório phpdoc:

(cd base; git pull)
(cd en;   git pull)

cd pt_BR
git fetch upstream
git checkout master
git merge upstream/master -m "Upstream merge."
cd ..

Isso vai atualizar todos os repositórios git e baixar no seu fork quaisquer alterações realizadas no repositório espelho. Após atualizar é interessante também executar o seguinte:

php base/configure.php --with-lang=pt_BR --enable-xml-details

Esse script verifica a integridade dos fontes XML. Está tudo bem se no final aparecer um gatinho em ASCII art. Se acabar em erro o jeito é trabalhar no erro primeiro, já que começar com o manual inconsistente impede de realizar o passo 3.

Para facilitar, você pode criar um script bash que faça tudo isso. Crie um arquivo chamado conf.sh com o seguinte conteúdo:

(cd base;  git pull)
(cd en;    git pull)
cd pt_BR
git fetch upstream
git checkout master
git merge upstream/master -m "Upstream merge."
git status
cd ..
php base/configure.php --with-lang=pt_BR --enable-xml-details

Para tornar esse arquivo executável, execute um chmod +x conf.sh. Para executar basta rodar ./conf.sh ou um source conf.sh.

E aqui surge a primeira regra geral: Antes de começar, atualize e valide.

Passo 2: Traduzir ou atualizar um arquivo

O manual do PHP é um documento enorme, e trabalho não falta. Você pode escolher que tipo de contribuição realizar. Em ordem de prioridade:

  1. Arquivos desatualizados: Arquivos anteriormente traduzidos mas que foram posteriormente tiveram os originais atualizados.

  2. Arquivos sem tags: Arquivos traduzidos mas que a ausência de tags de tradução (ver abaixo) impedem acompanhar a sincronia.

  3. Not in EN tree: Arquivos que existem na tradução mas não original. Provavelmente movidos, ou mesmo a apagar.

  4. Arquivos não traduzidos: Aparecem no manual totalmente em inglês.

Os links acima apontam para um ferramental que se encontra ainda desatualizado (Janeiro/2021). Para conseguir uma relação atualizada, execute:

wget -O revcheck.php https://raw.githubusercontent.com/alfsb/phpdoc/main/revcheck.php
php revcheck.php pt_BR > revcheck.html
xdg-open revcheck.html

O processo de tradução em si é bem simples. Arquivos originais e traduzidos tem os mesmos caminhos relativos, mudando apenas a pasta inicial, en ou pt_BR. No caso de arquivo inexistente na tradução, basta criá-lo. Depois é abrir ambos os arquivos, original e tradução, copiar o XML em inglês e traduzir a parte texto, preservando tags e comentários XML.

Dica 1: Veja como configurar um editor de texto simples, que permita abrir os arquivos lado a lado ou que permitam alternar abas rapidamente via teclado. Abrir arquivos lado a lado ajuda na hora de novas traduções, e o rápido alternar abas permite descobrir alterações estruturais "no olho".

Dica 2: Tente preservar a quantidade linhas igual entre os dois arquivos, além de manter as tags estruturais nas mesmas linhas entre original e tradução. Isso fará muita diferença depois, na hora de atualizar as traduções. É muito mais fácil detectar o que é preciso atualizar quando essa “compatibilidade estrutural” é preservada.

Sempre que terminar uma tradução ou atualização, não se esqueça de sincronizar a tag de revisão, conforme explicado o formato explicado a seguir:

<!-- EN-Revision: hhhh Maintainer: xxxx Status: ssss --><!-- CREDITS: xxxx,yyyy -->

Onde:

  • hhhh: É o hash completo que aparece nas primeiras linhas do arquivo original em inglês.
  • xxxx: É o login do tradutor que último mexeu no arquivo, ou seja, você. Caso possua uma credencial PHP.net é o seu login puro (sem arroba), caso não possua uma credencial preencher com @seu.login.github (com arroba).
  • ssss: É um código de status, conforme abaixo.
  • yyyy,zzzz: Uma relação de todas as pessoas que trabalharam no arquivo. Logins separados por vírgula.

Os valores previstos para o Status são:

  • ready: Significa que a tradução está pronta.
  • revision: Significa que a tradução está pronta, mas que o tradutor solicita que outra pessoa revise.
  • wip: Sigla de work in progress, uma tradução que está no meio do caminho. Entre em contato maintainer do arquivo ou discuta a situação na lista, caso encontre um arquivo ainda wip depois de muito tempo.

Basicamente o que você faz é atualizar o texto traduzido, sincronizar o hash da tradução a partir do hash no arquivo original, inserir seu login em Maintainer: e acrescentar seu login na lista CREDITS:.

Observação: Os scripts de monitoração das traduções utilizam expressões regulares bem simples para ler a tag de revisão, então os espaços, ordem e formato geral das tags precisam ser exatamente como nos exemplos acima. De outra forma o script não rastreará corretamente as traduções.

Passo 3: Validar a consistência do manual

Antes fazer um push no seu repositório ou enviar um pull request ao repositório espelho, é estritamente necessário validar se a alteração não quebra a compilação do manual. Isso é feito através do comando:

php base/configure.php --with-lang=pt_BR --enable-xml-details

Caso tenha definido o arquivo conf.sh acima, basta executá-lo. E daí vem a segunda regra geral: Antes de gerar o patch atualize e valide.

Ou o que é mais fácil de lembrar: Sempre execute o ./conf.sh, ao começar ou acabar!

Observação 1: O conf.sh atualiza o manual antes de compilar. Isso pode ser bom por um lado (melhora a certeza que o manual compilará depois que enviar suas alterações), mas pode ter o efeito colateral de quebrar a sua compilação local por causa de alguma alteração de terceiros. Isso dificulta o problema de separar se a quebra é por conta de alguma alteração sua ou de algo que foi trazido na atualização. Mas não tem muita escapatória. Ninguém vai aplicar um patch com o manual quebrado, menos vai aplicar um patch que aparentemente quebre a compilação do manual, então melhor correr atrás e ter o manual sempre validando.

Observação 2: Existe uma maneira de visualizar suas alterações localmente, sem esperar a publicação no site oficial. Mas isso também exige a instalação de um toolchain bem mais complicado. É bem possível conviver só validando o manual localmente, e revisar o resultado visual direto no servidor http://docs.php.net/manual/pt_BR/, um mirror que é atualizado a cada seis horas. Caso a alteração não apareça aqui depois desse tempo, pode ter ocorrido algum problema na compilação automática do manual, e os logs devem ser verificados.

Passo 4: Envio do seu trabalho

Após realizar as alterações desejadas, execute um git status para verificar a lista de arquivos modificados, ver se não teve alguma coisa inesperadamente alterada.

Todos os arquivos ou alterações que quiser enviar devem ser acrescentados no commit (mesmo em arquivos pré-existentes), ou seja, é preciso fazer o git add em todos os arquivos, assim:

git add caminho/arquivo.xml

Para fechar um pacote de alterações no seu repositório local, rode um

git commit -m "MESSAGE"

sendo MESSAGE um resumo das suas alterações, em inglês. Pode ser um simples Update translation.. No Guia há uma descrição de como escrever mensagens melhores, que inclusive disparam comandos automatizados.

É preciso ainda enviar o commit local ao seu repositório GitHub. Para tanto execute um:

git push origin master

Por fim, deve-se criar um pull request com as alterações. Ver detalhes em 1, 2 e 3.

Ufa!

Parece muita coisa, e da primeira vez deve dar medo. Mas não se preocupe. Depois quer fizer um ou duas vezes, fica bastante automático, e o medo desaparece.

E é isso. Terminou, daí é GOTO 1.

Clone this wiki locally