-
Notifications
You must be signed in to change notification settings - Fork 104
Roteiro git
Este roteiro é destinado àqueles que querem contribuir com o manual do PHP utilizando o git em linha de comando. É especificamente destinado aos que preferem esse ambiente em particular, mas também àqueles 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.
AVISO:: Boa parte dos comandos
gitabaixo não foram revisados, e usam um fluxograma adaptado de várias fontes. Caso você seja um usuário proficiente dogit, solicitamos a revisão e contribuição dos comandos abaixo. Os scripts abaixo tentam superar a questão de falta de familiaridade com o git e outros tantos comandos utilizados em paralelo (umconf.shque somente baixa dados e roda o teste,push.shque squash+push, ewipe.shpara apagar alterações locais e fazer um rebase).
Para contribuir com o manual são quatro passos, assim resumidos:
- Baixar ou atualizar os arquivos fontes;
- Traduzir ou sincronizar uma tradução;
- Validar a consistência do manual;
- 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.
Os fontes oficiais são gerenciados nos repositórios GitHub oficiais. Autores e tradutores com acesso podem operar contra o repositório oficial diretamente. Para utilizar esse roteiro sem acesso (o caso mais comum), é preciso ir no repositório 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
GU="seu_login_github_aqui"
# Primeira baixa de arquivos
mkdir phpdoc
cd phpdoc
git clone [email protected]:php/doc-base.git doc-base
git clone [email protected]:php/doc-en.git en
git clone [email protected]:$GU/doc-pt_br pt_BR
# Conjunto de scripts para facilitar o dia a dia
ln -s pt_BR/.tools/test/all.sh all.sh
ln -s pt_BR/.tools/test/conf.sh conf.sh
ln -s pt_BR/.tools/test/diff.sh diff.sh
ln -s pt_BR/.tools/test/find.sh find.sh
ln -s pt_BR/.tools/test/gind.sh gind.sh
ln -s pt_BR/.tools/test/open.sh open.sh
ln -s pt_BR/.tools/test/push.sh push.sh
ln -s pt_BR/.tools/test/test.sh test.sh
ln -s pt_BR/.tools/test/trim.sh trim.sh
ln -s pt_BR/.tools/test/wipe.sh wipe.sh
# Configurando o espelho como uma fonte de atualizações
# (pular esse passo quem tiver o acesso direto)
cd pt_BR
git remote add upstream https://github.com/php/doc-pt_br
git config pull.rebase true
git pull
cd ..
cd ..
Isso irá criar uma pasta phpdoc no mesmo diretório que os comandos forem executados. Todo o ambiente de tradução está configurado aqui. Para entrar na pasta e ver o seu conteúdo:
cd phpdoc
ls
Haverá três diretórios aqui:
- doc-base: Contém scripts e outros arquivos necessários para 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 procedimento normal é uma repetição dos passos seguintes.
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:
#!/bin/bash
(cd doc-base; git pull)
(cd en; git pull)
(cd pt_BR; git pull)
(cd pt_BR; git status)
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 doc-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 o dia a dia, esses dois procedimentos comuns estão consolidados em dois scripts já instalados pelos passos acima. A saber:
-
all.sh: Atualiza os fontes, recompila o manual e gera um revcheck.html local. -
conf.sh: Atualiza os fontes e recompila o manual
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:
- Lista de arquivos desatualizados.
- Lista de arquivos sem rastreamento.
- Lista de arquivos abandonados
- Lista de arquivos não traduzidos.
Os links acima apontam para uma listagem que pode estar desatualizada. Para conseguir uma relação atualizada, você pode criar um revcheck.html localmente, executando:
php doc-base/scripts/revcheck.php pt_BR > revcheck.html
xdg-open revcheck.html
O script all.sh já faz esse passo, então ele é script bom para começar um dia de tradução.
O processo de tradução em si é bem simples. Arquivos originais e traduzidos têm os mesmos caminhos relativos, mudando apenas a pasta inicial, en ou pt_BR. No caso de arquivo inexistente na tradução, basta copiar ele do en para pt_BR, mantendo o caminho interno. 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.
O script open.sh facilita em muito esse procedimento de ficar abrindo o mesmo arquivo em duas pastas diferentes.
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.
Os arquivos originais podem conter um comentário XML bem no começo do arquivo, com o seguinte texto:
<!-- $Revision:$ -->
Nos arquivos traduzidos essa linha deve ser substituída por uma linha no formato:
<!-- EN-Revision: hhhh Maintainer: xxxx Status: ssss --><!-- CREDITS: zzzz,yyyy,xxxx -->
Onde:
-
hhhh: É o hash completo do arquivo em inglês que aparece nas ferramentas de documentação. -
xxxx: É o apelido do tradutor que se responsabiliza em manter esse arquivo atualizado. Informar sua credencial php.net, ou seu login no GitHub, ou aindanoneou_caso seja uma contribuição esporádica (explicado abaixo). -
ssss: É um código de status, explicado abaixo. -
zzzz,yyyy,xxxx: Uma relação de todas as pessoas que trabalharam no arquivo, incluindo você. Logins separados por vírgula.
Os valores previstos para o Status são:
-
ready: Significa que a tradução está pronta. -
rev: 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 aindawipdepois de muito tempo. Arquivoswipsão altamente desencorajados na tradução brasileira.
Basicamente o que você faz é atualizar o texto traduzido, sincronizar o hash conforme a ferramenta de controle, acrescentar seu login na lista CREDITS:.
Você pode também preencher seu login em Maintainer:, caso queira puxar para si a responsabilidade de manter o arquivo atualizado. Tome o cuidado de verificar se o nome do Maintainer anterior está na lista de CREDITS, e se não tiver, acrescente-o também, antes do seu. Arquivos com o Maintainer preenchido com none ou _ não tem um Maintainer designado, e podem ser livremente alterados. Arquivos desatualizados a mais de 90 dias também podem ser mexidos livremente, mesmo com Maintainer preenchido, e nesses casos qualquer outro tradutor pode também puxar o Maintainer para si.
Pode ocorrer do arquivo original não conter uma linha com <!-- $Revision:$ -->. Nesses casos, as tags comentário de revisão e crédito devem ser colocadas ao final da primeira linha.
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 rastreia corretamente as traduções.
Antes de 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 doc-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.
Após realizar as alterações desejadas, execute um ./conf.sh para verificar a lista de arquivos modificados, e ver se não teve alguma coisa inesperadamente alterada.
Para enviar suas alterações você deve executar uma sequência de passos bem detalhada:
- Fazer um pull & merge do repositório remoto;
- Acrescentar todos os arquivos novos e modificados no staging do git;
- Criar um commit com uma mensagem com as modificações do staging;
- Fazer um push desse commit local, o publicando no repositório remoto.
- Fazer um pull request, no GitHub.
Os passos locais estão automatizados no script ./push.sh, que aceita um único parâmetro, a mensagem a ser definida no commit, e pode ser invocado assim:
./push.sh "Atualiza arquivo caminho/do/arquivo.xml"
Ou ainda:
./push.sh "Atualiza arquivos de caminho/interno/"
A mensagem pode ser um simples Update translation. no caso de atualizações de texto traduzido, mas deve ser bem mais detalhada no caso de alterações em scripts. No guia de edição há uma descrição de como escrever mensagens melhores, que inclusive disparam procedimentos automatizados.
Com isso, suas alterações foram encaminhadas ao seu fork particular. O último passo é criar um pull request com essa alterações, de forma que as alterações com o seu fork sejam encaminhadas para revisão no repositório oficial. Caso não sabia como fazer isso, veja os detalhes em 1, 2 e 3.
Pode acontecer do seu repositório ficar dessincronizado. Isso ocorre porque na prática são dois repositórios completamente separados, ainda que tenham uma história em comum, e porque o repositório oficial continua recebendo alterações de outras pessoas, o que acaba não refletido no seu fork.
Assim, após o seu pull request ser aceito, ou antes de começar uma nova tradução, é importante sincronizar o seu fork. Esses passos, que ocorrem no GitHub, estão descritos no final do roteiro web.
Ufa!
Parece muita coisa, e da primeira vez deve dar medo. Mas não se preocupe. Depois que fizer um ou duas vezes, fica bastante automático, e o medo desaparece.
E é isso. Terminou, daí é GOTO 1.