-
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:: Os comandos e procedimentos abaixo ainda foram pouco revisados. Caso você seja um usuário proficiente do
git, solicitamos a revisão e contribuição dos comandos abaixo. Os scripts abaixo tentam superar a questão de falta de familiaridade com ogite outros tantos comandos que são quase sempre utilizados em conjunto.
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 direto podem operar contra o repositório oficial. Mas nesse roteiro é mostrado o uso de um repositório fork, que permite a contribuição de pessoas sem acesso direto (que é o caso mais comum, aliás).
O primeiro passo é na verdade realizado no site no GitHub. Abra uma conta lá, e depois disso, navegue até a URL de criação do seu fork, que é: https://github.com/php/doc-pt_br/fork
Após criado o seu fork, é necessário também que o git em linha de comando esteja instalado no computador. Num terminal, instale e verifique a instalação:
sudo apt-get install git
git --version
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 fork com uma fonte de atualizações
# (pular esse passo quem tiver o acesso direto)
git -c pt_BR remote add upstream https://github.com/php/doc-pt_br
git -c pt_BR remote set-url --push upstream /dev/null
git -c pt_BR config pull.rebase true
# O GitHub reclama se você não tiver nome e email
# preenchidos, então vamos adiantar esse passo.
git -c pt_BR config user.name "Nome Sobrenome"
git -c pt_BR config user.email "[email protected]"
Isso irá criar uma pasta phpdoc no mesmo diretório que os comandos forem executados. Todo o ambiente de tradução está configurado aqui.```
Haverá três diretórios nesse diretório:
- doc-base: Contém scripts e outros arquivos necessários para a compilação do manual;
- en: Contém os arquivos originais do manual, em inglês;
- pt_BR: Contém os arquivos traduzidos do manual para português do Brasil.
Você somente vai mexer com arquivos dentro de pt_BR. Para ver se tudo deu certo, faça um git -C pt_BR 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.
Antes de começar algum trabalho, é importante atualizar todos os fontes e verificar se o manual está compilando. Isso é realizado através do comando:
./conf.sh
Caso tenha curiosidade, inspecione o conteúdo desse script, que mostra a sequência de comandos de atualização e compilação do manual.
Executar esse comando vai ser seu primeiro contato com as mensagens que aparecem durante a compilação, que são muitas. Mas não se angustie. Se no final aparecer um gatinho em ASCII art, é porque as coisas deram certo o suficiente. Mas se tiver um tempo, dê uma lida nas mensagens, para conhecê-las um pouco, e para procurar alertas de falhas e erros.
O principal comando de compilação é a linha:
php doc-base/configure.php -q --with-lang=pt_BR --enable-xml-details --disable-xpointer-reporting
Esse script verifica a integridade dos fontes XML, e na verdade faz muitas outras coisas também. Como o manual do PHP é separado em literalmente milhares de arquivos, é preciso juntá-los todos em único ponto, misturando arquivos em inglês e traduzidos, fora outros detalhes. Tudo isso é feito pelo doc-base/configure.php, e por isso ele deve ser rodado com frequência.
Há na verdade dois scripts interessantes para se utilizar sempre que for começar uma tradução ou atualização. A saber:
-
all.sh: Atualiza e compila o manual, e gera umrevcheck.htmllocal. Bom para executar no começo de um dia de trabalho, e; -
conf.sh: Atualiza e compila o manual, bom de executar a cada arquivo alterado.
Nota: O --disable-xpointer-reporting omite alguns avisos que são comuns e normalmente não são fatais. Mas caso o manual esteja com problema de compilação, remover essa opção pode ajudar a esclarecer a razão.
O manual do PHP é um documento enorme, e trabalho não falta. Você pode escolher que tipo de contribuição realizar, embora normalmente exista um issue aberto no GitHub que serve de coordenação, para evitar trabalhos duplicados.
Existe um relatório que lista a situação do manual e quais arquivos precisam de atenção dos tradutores, chamado de revcheck. O comando ./all.sh cria ele localmente, mas você pode consultar uma versão deste relatório online, pelos links a seguir. Em ordem de prioridade, você deve se concentrar nos:
- Arquivos desatualizados.
- Arquivos sem rastreamento.
- Arquivos não traduzidos.
Os links acima são atualizados uma vez por dia, e por isso mesmo podem estar desatualizados. Para saber a situação exata dos/nos seus clones locais, você pode visualizar o revcheck.html, criado pelo ./all.sh, ou se quiser criar apenas o revcheck.html sem mexer em mais nada, isso é possível com os comandos seguintes:
php doc-base/scripts/revcheck.php pt_BR > revcheck.html
xdg-open revcheck.html
Já o processo de tradução em si é bem simples. Arquivos originais e traduzidos têm os mesmos caminhos dentro dos repositórios, mudando apenas a pasta inicial, en ou pt_BR. No caso de arquivo inexistente na tradução, basta copiar o arquivo 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 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 permita 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 encontrar o que é preciso atualizar quando essa “compatibilidade de linhas” é preservada.
TODO: Adaptar open.sh para usar o editor configurado no git, ou Gnome/KDE padrão, e por fim descrever essa funcionalidade aqui.
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 para o seu fork ou um pull request contra o repositório oficial, é estritamente necessário validar se a alteração não quebra a compilação do manual. Isso é feito através do comando:
./conf.sh
ou
php doc-base/configure.php --with-lang=pt_BR --enable-xml-details
Sempre fazer isso antes de fazer qualquer comando git.
Ou o que é mais fácil de lembrar: Sempre execute o ./conf.sh, ao antes e depois de mexer em qualquer arquivo!
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 compila 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 que exige a instalação de um toolchain bem mais extenso.
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:
- Executar
git addpara cada arquivo novo ou alterado; - Criar um commit local com um
git commit; - Enviar o commit local para o seu fork, através de um
git push; - Iniciar um Pull request a partir do seu fork;
Caso isso pareça muito complicado, alguns scripts facilitam a vida. Primeiro faça um:
./diff.sh
Isso vai mostrar todas as alterações que o git percebeu que você fez. Confira tudo, para ver se não tem nada fora do lugar ou se tem alguma alteração indesejada. Se estiver tudo certo, daí você pode fazer um:
./push.sh "Descrição resumida da tradução ou atualização."
A mensagem pode ser simples ou detalhada no caso de mexer em XML, mas deve ser bem detalhada no caso de alterações em código. No guia de edição há uma descrição de como escrever mensagens melhores, que inclusive podem disparar procedimentos automatizados.
Feitos o diff e o push, suas alterações foram encaminhadas ao seu fork particular. O último passo é criar um pull request com essas alterações, de forma que as alterações do seu fork sejam encaminhadas para revisão e aplicaçã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, com o GitHub mostrando uma mensagem parecida com This branch is N commits ahead. Isso não causa problemas, mas acaba sendo chato. Em um dia que não tiver nenhum trabalho em andamento ou pull request aberto, ao final deste guia tem uma explicação de como resolver, e depois ainda, de como evitar completamente esse problema.
Ufa!
Parece muita coisa, e da primeira vez deve dar até 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.
Depois de algum tempo, você pode notar que o seu repositório fork no GitHub apresenta a mensagem This branch is N commits ahead, mesmo após todas as suas alterações terem sido aceitas e todos os repositórios estarem sincronizados. Uma (longa) explicação das causas dessa eterna dessincronização é dada neste link, mas aqui focaremos apenas em como fazer a mensagem sumir.
Só adianto que se tratam de alterações em princípio destrutivas, e por isso mesmo que só devem ser realizadas no seu repositório fork, e nunca contra os repositórios oficiais. Aviso dado, bora lá. Os comandos para remover a mensagem são os seguintes, separados em três blocos:
git fetch upstream
git switch master
git rebase -s ours upstream/master
git push --force origin +master
O primeiro comando apenas baixa dados do repositório oficial no seu fork. Se ele falhar, veja e execute os comandos relacionados a upstream mencionados na seção "Configurações iniciais".
O segundo grupo de comandos já envolve alterações destrutivas. No caso o rebase reescreve os commits no histórico local, e isso dessincroniza o fork GitHub do seu clone local. O sinal que as coisas deram certo é o rebase terminar com a mensagem Successfully rebased and updated refs/heads/master. Caso alguma coisa dê errado, basta executar um git rebase --abort, que tudo volta como antes.
Por fim, o git push --force sobrescreve o ramo master do repositório remoto origin com os dados locais, efetivamente apagando dados no repositório remoto. O repositório origin deve ser o seu fork GitHub no caso, e é criado automaticamente pelo git clone. Note que entre os comandos de configuração, tomamos o cuidado de invalidar a URL de push de upstream, e assim evitar acidentes.
Porém isso não evita a rota destrutiva que tradutores com acesso direto sempre possuem, então as pessoas com acesso direto devem tomar cuidados redobrados, de somente executar esses comandos em checkouts de repositórios secundários (ou melhor ainda, nunca executar esses comandos).
TODO