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

Trabalhando no repositório Git

Vamos direto ao assunto — nesta seção você aprenderá como criar uma cópia local do repositório main, como manter esse repositório atualizado e como enviar seu trabalho. Também explicaremos como trabalhar nas traduções.

Obtenha uma cópia local

Primeiro, instale o Git. Em seguida, configure o Git e insira seu nome e endereço de e-mail. Se você é um(a) usuário(a) novo(a) do Git, provavelmente é uma boa ideia primeiro ler a documentação geral do Git.

Seu próximo passo é clonar o repositório (em outras palavras: fazer uma cópia local dele). Existem duas maneiras para fazer isso:

Dica: clonar todo o repositório webwml requer o download de aproximadamente 1,3 GB de dados, o que pode ser bastante se você estiver em uma conexão de Internet lenta ou instável. Portanto, é possível definir uma profundidade mínima para um download inicial menor: 

  git clone [email protected]:webmaster-team/webwml.git --depth 1

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

  git fetch --deepen=1000 # aprofunda o repo para mais 1000 commits
  git fetch --unshallow   # busca todos os commits ausentes, converte o repositório para um completo

Você também pode obter apenas um subconjunto das páginas:

  1. git clone --no-checkout [email protected]:webmaster-team/webwml.git
  2. cd webwml
  3. git config core.sparseCheckout true
  4. Crie o arquivo .git/info/sparse-checkout dentro do diretório webwml para definir o conteúdo que você deseja obter. Por exemplo, se deseja recuperar apenas os arquivos base, traduções do inglês, catalão e espanhol, o arquivo será dessa forma: 
          /*
      !/[a-z]*/
      /english/
      /catalan/
      /spanish/
  5. A seguir, poderá obter o repo: git checkout --

Envie as mudanças locais

Mantenha seu repo local atualizado

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

  git pull

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

É altamente recomendável manter seu diretório de trabalho Git local limpo antes de executar git pull e começar a editar alguns arquivos. Se você tiver alterações que não foram feitos commit, ou commits locais que não estão presentes no repositório remoto no branch atual, executar git pull criará automaticamente merge commits ou até mesmo falhará devido a conflitos. Por favor, considere manter seu trabalho inacabado em outro branch ou usar comandos como git stash.

Nota: O Git é um sistema de controle de versão distribuído (não centralizado). Isso significa que quando você fizer o commit das alterações, elas serão armazenadas apenas em seu repositório local. Para compartilhá-los com outras pessoas, você também precisará enviar suas alterações para o repositório central no Salsa.

Exemplo: editando alguns arquivos

Vejamos um exemplo mais prático e uma sessão de edição típica. Estamos assumindo que você obteve uma cópia local do repositório usando git clone. Seus próximos passos são:

  1. git pull
  2. Agora você pode começar a editar e fazer alterações nos arquivos.
  3. Quando terminar, faça o commit de suas alterações em seu repositório local: 
        git add caminho/para/os/arquivos
    git commit -m "Sua mensagem de commit"
  4. Se você tiver acesso ilimitado de escrita no repositório remoto webwml, poderá enviar suas alterações diretamente para o repositório no Salsa: git push
  5. Se não tiver acesso direto de escrita ao repositório webwml, envie suas alterações com um merge request ou entre em contato com outros(as) desenvolvedores(as) para obter ajuda.

Fechando bugs do Debian Bugs com commits no Git

Se você incluir Closes: #nnnnnn no conteúdo do log do seu commit, então o bug de número #nnnnnn será fechado automaticamente quando você enviar suas alterações. A forma precisa disso é a mesma que na política Debian.

Links com HTTP/HTTPS

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

O repositório Git rejeitará commits contendo links HTTP simples para sites web do Debian que suportam HTTPS, ou contendo links HTTPS para sites web Debian/DebConf/SPI que são conhecidos por não suportarem HTTPS ou usarem certificados assinados apenas pela SPI.

Trabalhando as traduções

As traduções devem sempre ser mantidas atualizadas com o 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 foi baseada. Se você alterar os arquivos traduzidos, precisará atualizar o cabeçalho translation-check para corresponder ao hash do commit Git da alteração correspondente no arquivo em inglês. Você pode identificar o hash com o seguinte comando:

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

Se você fizer uma nova tradução de um arquivo, por favor use o script copypage.pl. Ele cria um template para seu idioma, incluindo o cabeçalho de tradução correto.

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

smart_change.pl é um script projetado para tornar mais fácil atualizar arquivos originais e suas traduções juntos. Existem duas maneiras de usá-lo, dependendo das alterações que você está fazendo.

Veja como usar smart_change.pl e como atualizar os cabeçalhos translation-check quando estiver trabalhando em arquivos manualmente:

  1. Faça as alterações nos arquivos originais e faça o commit das suas alterações.
  2. Atualize as traduções.
  3. Execute smart_change.pl -c COMMIT_HASH (use o hash do commit das alterações nos arquivos originais). Ele pegará as alterações e atualizará os cabeçalhos dos arquivos traduzidos.
  4. Revise as alterações (por exemplo, com git diff).
  5. Faça o commit das alterações de tradução.

Como alternativa, você pode trabalhar com expressões regulares para fazer várias alterações nos arquivos em uma única passagem:

  1. Execute smart_change.pl -s s/FOO/BAR/ origfile1 origfile2 ...
  2. Revise as alterações (por exemplo, com git diff).
  3. Faça o commit dos arquivos originais.
  4. Execute smart_change.pl origfile1 origfile2 (ou seja, sem o regexp desta vez). Ele agora apenas atualizará os cabeçalhos dos arquivos traduzidos.
  5. Por fim, faça o commit das alterações de tradução.

É certo que isso requer um pouco mais de esforço do que o primeiro exemplo, pois envolve dois commits, mas é inevitável devido à maneira como os hashes do Git funcionam.

Acesso de escrita ao repositório Git

O código-fonte do site web do Debian é gerenciado com o Git e localizado em https://salsa.debian.org/webmaster-team/webwml. Por padrão, convidados(as) não têm permissão para enviar os commits para o repositório de código-fonte. Se você deseja contribuir com o site web do Debian, precisa de algum tipo de permissão para obter acesso de escrita no repositório.

Acesso ilimitado de escrita

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

Se você é novo(a) no desenvolvimento do site web do Debian e não tem experiência anterior, por favor envie um e-mail para [email protected] e se apresente antes de solicitar acesso ilimitado de escrita. Seja gentil e nos conte mais sobre você, por exemplo, em qual parte do site web planeja trabalhar, quais idiomas fala, e também se há outro(a) membro(a) da equipe do Debian que pode atestar por você.

Merge Requests

Não é necessário obter acesso ilimitado de escrita no repositório — você sempre pode enviar um merge request e permitir que outros(as) desenvolvedores(as) revisem e aceitem seu trabalho. Por favor, siga o procedimento padrão para solicitações de merge requests fornecido pela plataforma Salsa GitLab por meio de sua interface web e leia os dois documentos a seguir:

Por favor observe que os merge requests não são monitoradas por todos(as) os(as) desenvolvedores(as) do site web. Portanto, pode levar algum tempo até que receba algum feedback. Se quer saber se sua contribuição será aceita ou não, por favor envie um e-mail para a lista de discussão debian-www e peça uma revisão.

Obtendo notificações

Se você está trabalhando no site web do Debian, provavelmente quer saber o que está acontecendo no repositório webwml. Há duas maneiras de se manter atualizado(a): notificações de commit e notificações de merge request.

Recebendo notificações de commit

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

Se deseja receber notificações sobre commits no repo webwml por e-mail, por favor assine o pseudopacote www.debian.org via tracker.debian.org e ative a palavra-chave vcs, seguindo estes passos (apenas uma vez):

  1. Abra um navegador web e vá para https://tracker.debian.org/pkg/www.debian.org.
  2. Assine o pseudopacote www.debian.org (você pode autenticar via SSO ou registrar um e-mail e senha, se ainda não estiver usando o tracker.debian.org para outros propósitos).
  3. Vá para https://tracker.debian.org/accounts/subscriptions, depois em >modify keywords, marque vcs (se não estiver marcado) e salve.
  4. A partir de agora, você receberá e-mails quando alguém fizer commit no repositório webwml.

Recebendo notificações de Merge Request

Se deseja receber e-mails de notificação sempre que houver novos merge requests enviadas para o repositório webwml no Salsa, você pode configurar suas opções de notificação na interface web seguindo estas etapas:

  1. Faça login na sua conta do Salsa e vá para a página do projeto.
  2. Clique no ícone do sino na parte superior da página inicial do projeto.
  3. Selecione o nível de notificação de sua preferência.