Enviando patches (Manual de referência do GNU Guix)

22.10 Enviando patches

O desenvolvimento é feito usando o sistema de controle de versão distribuído Git. Assim, o acesso ao repositório não é estritamente necessário. Aceitamos contribuições na forma de patches produzidos por git format-patch enviados para a lista de discussão guix-patches@gnu.org (veja Submitting patches to a project em Manual do usuário do Git). Os colaboradores são encorajados a reservar um momento para definir algumas opções do repositório Git (veja Configurando o Git) primeiro, o que pode melhorar a legibilidade dos patches. Desenvolvedores Guix experientes também podem querer dar uma olhada na seção sobre acesso de commit (veja Confirmar acesso).

Esta lista de discussão é apoiada por uma instância do Debbugs, o que nos permite acompanhar os envios (veja Rastreando Bugs e Mudanças). Cada mensagem enviada para essa lista de discussão recebe um novo número de rastreamento atribuído; as pessoas podem então acompanhar o envio enviando um e-mail para NÚMERO_DE_ISSÃO@debbugs.gnu.org, onde NÚMERO_DE_ISSÃO é o número de rastreamento (veja Enviando uma série de patches).

Por favor, escreva os logs de commit no formato de ChangeLog (veja Change Logs em GNU Coding Standards); você pode verificar o histórico de commit para exemplos.

Você pode ajudar a tornar o processo de revisão mais eficiente e aumentar a chance de que seu patch seja revisado rapidamente, descrevendo o contexto do seu patch e o impacto que você espera que ele tenha. Por exemplo, se seu patch estiver corrigindo algo que está quebrado, descreva o problema e como seu patch o corrige. Conte-nos como você testou seu patch. Os usuários do código alterado pelo seu patch terão que ajustar seu fluxo de trabalho? Se sim, conte-nos como. Em geral, tente imaginar quais perguntas um revisor fará e responda a essas perguntas com antecedência.

Antes de enviar um patch que adicione ou modifique uma definição de pacote, execute esta lista de verificação:

Se os autores do software empacotado fornecerem uma assinatura criptográfica para o tarball de lançamento, faça um esforço para verificar a autenticidade do arquivo. Para um arquivo de assinatura GPG separado, isso seria feito com o comando gpg --verify.
Reserve algum tempo para fornecer uma sinopse e descrição adequadas para o pacote. Veja Sinopses e descrições, para algumas diretrizes.
Execute guix lint pacote, sendo pacote o nome do pacote novo ou modificado e corrija quaisquer erros que forem relatados (veja Invocando guix lint).
Run guix style package to format the new package definition according to the project’s conventions (veja Invoking guix style).
Certifique-se de que o pacote compila em sua plataforma, usando guix build pacote.
We recommend you also try building the package on other supported platforms. As you may not have access to actual hardware platforms, we recommend using the qemu-binfmt-service-type to emulate them. In order to enable it, add the virtualization service module and the following service to the list of services in your operating-system configuration:
```
(service qemu-binfmt-service-type
 (qemu-binfmt-configuration
   (platforms (lookup-qemu-platforms "arm" "aarch64"))))
```
Então, reconfigure seu sistema.

Você pode criar pacotes para plataformas diferentes especificando a opção --system. Por exemplo, para compilar o pacote "hello" para as arquiteturas armhf ou aarch64, você executaria os seguintes comandos, respectivamente:
```
guix build --system=armhf-linux --rounds=2 hello
guix build --system=aarch64-linux --rounds=2 hello
```
Verifique se o pacote não usa cópias de software já disponíveis como pacotes separados.
Às vezes, os pacotes incluem cópias do código-fonte de suas dependências como uma conveniência para os usuários. No entanto, como uma distribuição, queremos garantir que esses pacotes acabem usando a cópia que já temos na distribuição, se houver. Isso melhora o uso de recursos (a dependência é criada e armazenada apenas uma vez) e permite que a distribuição faça alterações transversais, como aplicar atualizações de segurança para um determinado pacote de software em um único local e fazê-las afetar todo o sistema – algo que cópias incluídas impedem.
Dê uma olhada no perfil relatado por guix size (veja Invocando guix size). Isso permitirá que você perceba referências a outros pacotes retidos involuntariamente. Também pode ajudar a determinar se deve dividir o pacote (veja Pacotes com múltiplas saídas) e quais dependências opcionais devem ser usadas. Em particular, evite adicionar texlive como uma dependência: devido ao seu tamanho extremo, use o procedimento texlive-updmap.cfg.
Check that dependent packages (if applicable) are not affected by the change; guix refresh --list-dependent package will help you do that (veja Invocando guix refresh).
Verifique se o processo de compilação do pacote é determinístico. Isso normalmente significa verificar se uma compilação independente do pacote produz o mesmo resultado que você obteve, bit por bit.
Uma maneira simples de fazer isso é compilar o mesmo pacote várias vezes seguidas em sua máquina (veja Invocando guix build):
```
guix build --rounds=2 meu-pacote
```
Isso é suficiente para capturar uma classe de problemas comuns de não-determinismo, como registros de data e hora ou saída gerada aleatoriamente no resultado da compilação.

Outra opção é usar guix challenge (veja Invocando guix challenge). Você pode executá-lo uma vez que o pacote se tenha sido feito o commit e compilação por SUBSTITUTE-SERVER-1 para verificar se obtém o mesmo resultado que você fez. Melhor ainda: encontre outra máquina que possa compilá-lo e executar guix publish. Como a máquina de compilação remota provavelmente é diferente da sua, isso pode capturar problemas de não determinismo relacionados ao hardware - por exemplo, uso de extensões de conjunto de instruções diferentes – ou ao kernel do sistema operacional – por exemplo, confiança em uname ou arquivos de /proc.
Ao escrever documentação, por favor, use palavras de gênero neutras ao se referir a pessoas, como singular “they”, “their” , “them”, e assim por diante.
Verifique se o seu patch contém apenas um conjunto de alterações relacionadas. Agrupar mudanças não relacionadas juntas torna a revisão mais difícil e lenta.
Exemplos de alterações não relacionadas incluem a adição de vários pacotes ou uma atualização de pacote juntamente com correções para esse pacote.
Siga nossas regras de formatação de código, possivelmente executando o script guix style para fazer isso automaticamente para você (veja Formatação de código).
Quando possível, use espelhos no URL fonte (veja Invocando guix download). Use URLs confiáveis, não os gerados. Por exemplo, os arquivos do GitHub não são necessariamente idênticos de uma geração para a seguinte, portanto, nesse caso, geralmente é melhor clonar o repositório. Não use o campo name no URL: não é muito útil e se o nome mudar, o URL provavelmente estará errado.
Verifique se o Guix compila (veja Compilando do git) e resolva os avisos, especialmente aqueles sobre o uso de símbolos indefinidos.
Certifique-se de que suas alterações não quebrem o Guix e simule um guix pull com:
```
guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master
```

Ao postar um patch na lista de discussão, use ‘[PATCH] …’ como assunto. Se seu patch for aplicado em uma ramificação diferente de master, digamos core-updates, especifique-o no assunto como ‘[PATCH core-updates] …’.

Você pode usar seu cliente de e-mail, o comando git send-email (veja Enviando uma série de patches) ou o comando mumi send-email (veja Debbugs User Interfaces). Preferimos obter patches em mensagens de texto simples, seja em linha ou como anexos MIME. É aconselhável que você preste atenção se seu cliente de e-mail alterar algo como quebras de linha ou recuo, o que pode potencialmente quebrar os patches.

Espere algum atraso quando você enviar seu primeiro patch para guix-patches@gnu.org. Você tem que esperar até receber uma confirmação com o número de rastreamento atribuído. Confirmações futuras não devem ser atrasadas.

Quando um erro for resolvido, feche o tópico enviando um e-mail para NÚMERO_DE_ISSÃO-done@debbugs.gnu.org.