Próximo: , Anterior: , Acima: Contribuindo   [Conteúdo][Índice]


22.7 Enviando patches

Development is done using the Git distributed version control system. Thus, access to the repository is not strictly necessary. We welcome contributions in the form of patches as produced by git format-patch sent to the guix-patches@gnu.org mailing list (veja Submitting patches to a project em Git User Manual). Contributors are encouraged to take a moment to set some Git repository options (veja Configurando o Git) first, which can improve the readability of patches. Seasoned Guix developers may also want to look at the section on commit access (veja Commit Access).

This mailing list is backed by a Debbugs instance, which allows us to keep track of submissions (veja Tracking Bugs and Changes). Each message sent to that mailing list gets a new tracking number assigned; people can then follow up on the submission by sending email to ISSUE_NUMBER@debbugs.gnu.org, where ISSUE_NUMBER is the tracking number (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.

You can help make the review process more efficient, and increase the chance that your patch will be reviewed quickly, by describing the context of your patch and the impact you expect it to have. For example, if your patch is fixing something that is broken, describe the problem and how your patch fixes it. Tell us how you have tested your patch. Will users of the code changed by your patch have to adjust their workflow at all? If so, tell us how. In general, try to imagine what questions a reviewer will ask, and answer those questions in advance.

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

  1. 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.
  2. Reserve algum tempo para fornecer uma sinopse e descrição adequadas para o pacote. Veja Sinopses e descrições, para algumas diretrizes.
  3. Execute guix lint pacote, sendo pacote o nome do pacote novo ou modificado e corrija quaisquer erros que forem relatados (veja Invocando guix lint).
  4. Run guix style package to format the new package definition according to the project’s conventions (veja Invoking guix style).
  5. Certifique-se de que o pacote compila em sua plataforma, usando guix build pacote.
  6. 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.

    You can then build packages for different platforms by specifying the --system option. For example, to build the "hello" package for the armhf or aarch64 architectures, you would run the following commands, respectively:

    guix build --system=armhf-linux --rounds=2 hello
    guix build --system=aarch64-linux --rounds=2 hello
    
  7. 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.

  8. Take a look at the profile reported by guix size (veja Invocando guix size). This will allow you to notice references to other packages unwillingly retained. It may also help determine whether to split the package (veja Pacotes com múltiplas saídas), and which optional dependencies should be used. In particular, avoid adding texlive as a dependency: because of its extreme size, use texlive-updmap.cfg procedure instead.
  9. 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).
  10. 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.

    Another option is to use guix challenge (veja Invocando guix challenge). You may run it once the package has been committed and built by ci.guix.gnu.org to check whether it obtains the same result as you did. Better yet: Find another machine that can build it and run guix publish. Since the remote build machine is likely different from yours, this can catch non-determinism issues related to the hardware—e.g., use of different instruction set extensions—or to the operating system kernel—e.g., reliance on uname or /proc files.

  11. 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.
  12. 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.

  13. Please follow our code formatting rules, possibly running guix style script to do that automatically for you (veja Formatação de código).
  14. 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.
  15. Check if Guix builds (veja Compilando do git) and address the warnings, especially those about use of undefined symbols.
  16. Make sure your changes do not break Guix and simulate a guix pull with:
    guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master
    

When posting a patch to the mailing list, use ‘[PATCH] …’ as a subject, if your patch is to be applied on a branch other than master, say core-updates, specify it in the subject like ‘[PATCH core-updates] …’.

You may use your email client or the git send-email command (veja Enviando uma série de patches). We prefer to get patches in plain text messages, either inline or as MIME attachments. You are advised to pay attention if your email client changes anything like line breaks or indentation which could potentially break the patches.

Expect some delay when you submit your very first patch to guix-patches@gnu.org. You have to wait until you get an acknowledgement with the assigned tracking number. Future acknowledgements should not be delayed.

When a bug is resolved, please close the thread by sending an email to ISSUE_NUMBER-done@debbugs.gnu.org.


Próximo: Tracking Bugs and Changes, Anterior: Estilo de código, Acima: Contribuindo   [Conteúdo][Índice]