Usando o git para manipular o código-fonte do site web

Introdução

O Git é um sistema de controle de versão que ajuda a gerenciar várias pessoas trabalhando no mesmo material simultaneamente. Todo(a) usuário(a) pode manter uma cópia local de um repositório principal. As cópias locais podem estar na mesma máquina ou em todo o mundo. Usuários(as) podem então modificar a cópia local como assim desejarem e, quando o material modificado estiver pronto, fazer commit das alterações e fazer push para enviá-las de volta ao repositório principal.

O Git não permitirá que você faça push de um commit diretamente se o repositório remoto tiver commits (modificações) mais recentes que sua cópia local no mesmo branch. Nesse caso em que ocorra um conflito, por favor primeiro faça fetch e update na sua cópia local, e faça um rebase de suas novas modificações sobre o commit mais recente, conforme necessário.

Acesso de escrita ao repositório Git

Todo o código-fonte do site Debian é gerenciado no Git, localizado em https://salsa.debian.org/webmaster-team/webwml. Por padrão, convidados(as) não têm permissão para fazer push dos commits para o repositório de código-fonte. Você precisará de algum tipo de permissão para obter acesso de escrita ao repositório.

Acesso de escrita ilimitado

Se você precisar de acesso ilimitado de escrita ao repositório (por exemplo, você está prestes a se tornar um(a) contribuidor(a) frequente), considere solicitar o acesso de escrita por meio da interface da web https://salsa.debian.org/webmaster-team/webwml após fazer login na plataforma Salsa do Debian.

Se você é novo(a) no desenvolvimento do site web do Debian e não tem experiência anterior, envie também um e-mail para debian-www@lists.debian.org com sua apresentação pessoal antes de solicitar acesso ilimitado de escrita. Forneça algo útil em sua introdução, como em qual idioma ou em qual parte do site você planeja trabalhar e quem poderia atestar por você.

Escreva no repositório por meio de Merge Requests

Se você não pretende obter acesso ilimitado de escrita ao repositório ou não está habilitado a fazê-lo, você sempre pode enviar uma Merge Request e deixar que outros(as) desenvolvedores(as) revisem e aceitem seu trabalho. Por favor envie Merge Requests usando o procedimento padrão fornecido pela plataforma GitLab do Salsa por meio de sua interface web (para mais detalhes leia fluxo de trabalho de um fork de um projeto e quando você trabalha em um fork ).

As Merge Requests não são monitoradas por todos(as) os(as) desenvolvedores(as) do site web, portanto, nem sempre elas podem ser processadas rapidamente. Se você não tem certeza se sua contribuição será aceita, por favor envie um e-mail para a lista de discussão debian-www e solicite uma revisão.

Trabalhando no repositório

Obtendo uma cópia local do repositório

Primeiro, você precisa instalar o git para trabalhar com o repositório. Em seguida, configure os detalhes de usuário(a) e do e-mail no seu computador (consulte a documentação geral do git para saber como fazer isso). Em seguida, você pode fazer um clone do repositório (em outras palavras, faça uma cópia local) de uma de duas maneiras.

A maneira recomendada de trabalhar no webwml é primeiro criar uma conta no salsa.debian.org e habilitar o acesso SSH ao git, fazendo o upload de uma chave pública SSH na sua conta salsa. Veja as páginas de ajuda do Salsa para obter mais detalhes sobre como fazer isso. Em seguida, você pode fazer o clone do repositório webwml usando o seguinte comando:

   git clone git@salsa.debian.org:webmaster-team/webwml.git

Se você não possui uma conta no salsa, um método alternativo é fazer o clone do repositório usando o protocolo HTTPS:

  git clone https://salsa.debian.org/webmaster-team/webwml.git

Isso fornecerá a mesma cópia do repositório localmente, mas você não poderá enviar diretamente as alterações diretamente dessa maneira.

A clonagem de todo o repositório webwml exigirá o download de cerca de 500MB de dados; portanto, pode ser difícil para pessoas com conexões de internet lentas ou instáveis. Você pode tentar a clonagem superficial (shallow clone) com profundidade mínima primeiro para um download inicial menor:

  git clone git@salsa.debian.org:webmaster-team/webwml.git --depth 1

Após obter um repositório utilizável (superficial), você pode aprofundar a cópia superficial local e, eventualmente, convertê-la em um repositório local completo:

  git fetch --deepen=1000 # aprofunda o repositório por mais 1000 commits
  git fetch --unshallow   # obtém todos commits em falta, converte o repositório em um completo

Checkout parcial de conteúdo

Você pode criar um checkout para apenas um subconjunto de páginas como este:

   $ git clone --no-checkout git@salsa.debian.org:webmaster-team/webwml.git
   $ cd webwml
   $ git config core.sparseCheckout true
   No webwml: crie o arquivo .git/info/sparse-checkout com um conteúdo
   como este (caso queira apenas arquivos base, traduções em inglês e português):
      /*
      !/[a-z]*/
      /english/
      /portuguese/
   Então:
   $ git checkout --

Enviando as alterações locais

Mantendo seu repositório local atualizado

A cada poucos dias (e definitivamente antes de começar algum trabalho de edição!), você deve executar

   git pull

para obter quaisquer arquivos do repositório que foram alterados.

É altamente recomendável manter seu diretório de trabalho local do git limpo antes de executar "git pull" e seguir o trabalho de edição. Se você tiver alterações ainda sem commit feito, ou commits locais que não estão presentes no repositório remoto no branch atual, fazer "git pull" criará automaticamente "merge commits" ou até falhará devido a conflitos. Por favor, considere manter seu trabalho inacabado em outro branch ou usar comandos como "git stash".

Nota: git é um sistema de controle de versão distribuído (ou seja, não centralizado). Isso significa que, quando você faz commit das alterações, elas serão armazenadas apenas no seu repositório local. Para compartilhá-las com outras pessoas, você também precisará usar push para enviar suas alterações ao repositório central do salsa.

Exemplo de edição de arquivos em inglês

Um exemplo de como editar arquivos em inglês no repositório de código-fonte do site é fornecido aqui. Após obter uma cópia local do repositório usando "git clone" e antes de iniciar o trabalho de edição, execute o comando a seguir:

   $ git pull

Agora faça alterações nos arquivos. Quando terminar, faça o commit de suas alterações no repositório local usando:

   $ git add caminho/para/arquivo(s)
   $ git commit -m "Sua mensagem de commit"

Se você tiver acesso ilimitado de escrita ao repositório remoto webwml, agora poderá enviar as alterações diretamente para o repositório Salsa:

   $ git push

Se você não possui acesso direto de escrita ao repositório webwml, considere enviar suas alterações usando a função Merge Request, conforme fornecida pela plataforma Salsa GitLab, ou solicitando ajuda a outros(as) desenvolvedores(as).

Este é um resumo muito básico de como usar o git para manipular o código-fonte do site Debian. Para mais informações sobre o git, leia a documentação do git.

Fechando bugs do Debian com commits git

Se você incluir Closes: #nnnnnn na entrada de log do commit, o bug de número #nnnnnn será fechado automaticamente quando você fizer push das suas alterações. A forma precisa disso é a mesma que da política do Debian.

Links usando HTTP/HTTPS

Muitos sites web do Debian têm suporte a SSL/TLS, portanto, por favor use links com HTTPS sempre que for possível e sensato. No entanto, alguns sites web do Debian/DebConf/SPI/etc não têm suporte a HTTPS ou usam penas o CA da SPI (e não um SSL CA confiável para todos os navegadores). Para evitar que cause exibição de mensagens de erro para não usuários(as) do Debian, não acrescente link com HTTPS para esses sites.

O repositório git rejeitará commits contendo links HTTP simples para sites web do Debian que têm suporte a HTTPS ou contendo links HTTPS para sites web do Debian/DebConf/SPI que são conhecidos por não ter suporte a HTTPS ou usar certificados assinados apenas pela SPI.

Trabalhando em traduções

As traduções devem sempre ser mantidas atualizadas em relação ao arquivo em inglês correspondente. O cabeçalho "translation-check" nos arquivos de tradução é usado para rastrear em qual versão do arquivo em inglês a tradução atual se baseou. Se você alterar os arquivos traduzidos, precisará atualizar o "translation-check" para corresponder ao hash do commit do git da alteração correspondente no arquivo em inglês. Você pode encontrar esse hash com

$ git log caminho/para/arquivo/em/inglês

Se você fizer uma nova tradução de um arquivo, use o script copypage.pl e ele criará um modelo para o seu idioma, incluindo o cabeçalho de tradução correto.

Alterações de tradução com smart_change.pl

smart_change.pl é um script desenvolvido para facilitar a atualização de arquivos originais e suas traduções juntos. Existem duas maneiras de usá-lo, dependendo das alterações que você está fazendo.

Para usar smart_change para atualizar os cabeçalhos de translation-check quando você estiver trabalhando em arquivos manualmente:

  1. Faça as alterações no(s) arquivo(s) original(is), e faça commit
  2. Atualize as traduções
  3. Execute smart_change.pl - ele vai pegar as alterações e atualizar os cabeçalhos nos arquivos de tradução
  4. Revise as alterações (p. ex., com "git diff")
  5. Faça commit das alterações de tradução

Ou, se você estiver usando smart_change com uma expressão regular para fazer várias alterações nos arquivos de uma só vez:

  1. Execute smart_change.pl -s s/FOO/BAR/ arq_orig1 arq_orig2 ...
  2. Revise as alterações (p. ex., com git diff)
  3. Faça commit do arquivo(s) original(is)
  4. Execute smart_change.pl arq_orig1 arq_orig2 (ou seja, sem a regexp desta vez); isto vai agora apenas atualizar os cabeçalhos nos arquivos de tradução
  5. Finalmente, faça commit das alterações de tradução

Isso é mais trabalhoso que o anterior (necessitando de dois commits), mas inevitável devido à maneira como hashes de commit do git funcionam.

Obtendo notificações

Recebendo notificações de commit

Configuramos o projeto webwml no Salsa para que os commits sejam mostrados no canal de IRC #debian-www.

Se você deseja receber notificações por e-mail quando houver commit no repositório webwml, por favor se inscreva no pseudopacote www.debian.org via tracker.debian.org e ative a palavra-chave vcs, seguindo estas etapas (apenas uma vez):

Recebendo notificações de Merge Request

Se você deseja receber e-mails de notificação sempre que houver novas Merge Requests enviadas na interface web do repositório webwml na plataforma GitLab do Salsa, você pode definir suas configurações de notificação para o repositório webwml na interface web, seguindo estas etapas: