@node Contribuindo
@chapter Contribuindo

Este projeto é um esforço cooperativo e precisamos da sua ajuda para fazê-lo
crescer! Por favor, entre em contato conosco por meio de
@email{guix-devel@@gnu.org} e @code{#guix} na rede IRC do Freenode. São
muito bem-vindas ideias, relatórios de bugs, patches e qualquer coisa que
possa ser útil para o projeto. Nós particularmente agradecemos a ajuda no
empacotamento das (@pxref{Diretrizes de empacotamento}).

@cindex código de conduta, de contribuidores
@cindex acordo de contribuição
Queremos oferecer um ambiente acolhedor, amigável e sem assédio, para que
todos possam contribuir com o melhor de suas habilidades. Para este fim,
nosso projeto usa um ``Acordo de contribuição``, que foi adaptado de
@url{https://contributor-covenant.org/}. Você pode encontrar uma versão
local no arquivo @file{CODE-OF-CONDUCT} na árvore de fontes.

Os contribuidores não são obrigados a usar seu nome legal em patches e
comunicação on-line; eles podem usar qualquer nome ou pseudônimo de sua
escolha.

@menu
* Compilando do git::        A mais recente e melhor.
* Executando guix antes dele ser instalado::  Truques de hacker.
* A configuração perfeita::  As ferramentas certas.
* Diretrizes de empacotamento::  Crescendo a distribuição.
* Estilo de código::        Limpeza do contribuidor.
* Enviando patches::         Compartilhe seu trabalho.
* Tracking Bugs and Patches::  Using Debbugs.
* Commit Access::            Pushing to the official repository.
* Updating the Guix Package::  Updating the Guix package definition.
@end menu

@node Compilando do git
@section Compilando do git

Se você quiser hackear o próprio Guix, é recomendado usar a versão mais
recente do repositório Git:

@example
git clone https://git.savannah.gnu.org/git/guix.git
@end example

@cindex authentication, of a Guix checkout
How do you ensure that you obtained a genuine copy of the repository? To do
that, run @command{guix git authenticate}, passing it the commit and OpenPGP
fingerprint of the @dfn{channel introduction} (@pxref{Invoking guix git
authenticate}):

@c ===========================================================================
@c
@c This file was generated with po4a. Translate the source file.
@c
@c ===========================================================================

@c The commit and fingerprint below must match those of the channel
@c introduction in '%default-channels'.
@example
git fetch origin keyring:keyring
guix git authenticate 9edb3f66fd807b096b48283debdcddccfea34bad \
  "BBB0 2DDF 2CEA F6A8 0D1D  E643 A2A0 6DF2 A33A 54FA"
@end example

@noindent
This command completes with exit code zero on success; it prints an error
message and exits with a non-zero code otherwise.

As you can see, there is a chicken-and-egg problem: you first need to have
Guix installed.  Typically you would install Guix System (@pxref{Instalação do sistema}) or Guix on top of another distro (@pxref{Instalação de binários}); in either case, you would verify the OpenPGP signature on
the installation medium.  This ``bootstraps'' the trust chain.

A maneira mais fácil de configurar um ambiente de desenvolvimento para o
Guix é, obviamente, usando o Guix! O comando a seguir inicia um novo shell
no qual todas as dependências e variáveis de ambiente apropriadas são
configuradas para hackear o Guix:

@example
guix environment guix --pure
@end example

@xref{Invocando guix environment}, for more information on that command.

If you are unable to use Guix when building Guix from a checkout, the
following are the required packages in addition to those mentioned in the
installation instructions (@pxref{Requisitos}).

@itemize
@item @url{https://gnu.org/software/autoconf/, GNU Autoconf};
@item @url{https://gnu.org/software/automake/, GNU Automake};
@item @url{https://gnu.org/software/gettext/, GNU Gettext};
@item @url{https://gnu.org/software/texinfo/, GNU Texinfo};
@item @url{https://www.graphviz.org/, Graphviz};
@item @url{https://www.gnu.org/software/help2man/, GNU Help2man (optional)}.
@end itemize

On Guix, extra dependencies can be added by instead running @command{guix
environment} with @option{--ad-hoc}:

@example
guix environment guix --pure --ad-hoc help2man git strace
@end example

Execute @command{./bootstrap} para gerar a infraestrutura do sistema de
compilação usando o Autoconf e o Automake. Se você receber um erro como
este:

@example
configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES
@end example

@noindent
provavelmente significa que o Autoconf não conseguiu encontrar o
@file{pkg.m4}, que é fornecido pelo pkg-config. Certifique-se de que
@file{pkg.m4} esteja disponível. O mesmo vale para o conjunto de macros
@file{guile.m4} fornecido pelo Guile. Por exemplo, se você instalou o
Automake em @file{/usr/local}, ele não procuraria arquivos @file{.m4} em
@file{/usr/share}. Nesse caso, você tem que invocar o seguinte comando:

@example
export ACLOCAL_PATH=/usr/share/aclocal
@end example

@xref{Macro Search Path,,, automake, The GNU Automake Manual}, para mais
informações.

Then, run @command{./configure} as usual.  Make sure to pass
@code{--localstatedir=@var{directory}} where @var{directory} is the
@code{localstatedir} value used by your current installation (@pxref{O armazenamento}, for information about this), usually @file{/var}.  Note that you
will probably not run @command{make install} at the end (you don't have to)
but it's still important to pass the right @code{localstatedir}.

Finally, you have to invoke @code{make && make check} to build Guix and run
the tests (@pxref{Executando a suíte de testes}).  If anything fails, take a look
at installation instructions (@pxref{Instalação}) or send a message to the
@email{guix-devel@@gnu.org, mailing list}.

From there on, you can authenticate all the commits included in your
checkout by running:

@example
make authenticate
@end example

The first run takes a couple of minutes, but subsequent runs are faster.

Or, when your configuration for your local Git repository doesn't match the
default one, you can provide the reference for the @code{keyring} branch
through the variable @code{GUIX_GIT_KEYRING}.  The following example assumes
that you have a Git remote called @samp{myremote} pointing to the official
repository:

@example
make authenticate GUIX_GIT_KEYRING=myremote/keyring
@end example

@quotation Nota
You are advised to run @command{make authenticate} after every @command{git
pull} invocation.  This ensures you keep receiving valid changes to the
repository.
@end quotation


@node Executando guix antes dele ser instalado
@section Executando guix antes dele ser instalado

Para manter um ambiente de trabalho saudável, você achará útil testar as
alterações feitas na árvore local de fontes sem realmente instalá-las. Para
que você possa distinguir entre o seu chapéude ''usuário final'' e sua
fantasia ''misturada''.

To that end, all the command-line tools can be used even if you have not run
@code{make install}.  To do that, you first need to have an environment with
all the dependencies available (@pxref{Compilando do git}), and then simply
prefix each command with @command{./pre-inst-env} (the @file{pre-inst-env}
script lives in the top build tree of Guix; it is generated by running
@command{./bootstrap} followed by @command{./configure}).  As an example,
here is how you would build the @code{hello} package as defined in your
working tree (this assumes @command{guix-daemon} is already running on your
system; it's OK if it's a different version):

@example
$ ./pre-inst-env guix build hello
@end example

@noindent
Similarly, an example for a Guile session using the Guix modules:

@example
$ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'

;;; ("x86_64-linux")
@end example

@noindent
@cindex REPL
@cindex read-eval-print loop
@dots{} e para um REPL (@pxref{Usando o Guile interativamente,,, guile,
Manual de referência do Guile}):

@example
$ ./pre-inst-env guile
scheme@@(guile-user)> ,use(guix)
scheme@@(guile-user)> ,use(gnu)
scheme@@(guile-user)> (define snakes
                       (fold-packages
                         (lambda (package lst)
                           (if (string-prefix? "python"
                                               (package-name package))
                               (cons package lst)
                               lst))
                         '()))
scheme@@(guile-user)> (length snakes)
$1 = 361
@end example

If you are hacking on the daemon and its supporting code or if
@command{guix-daemon} is not already running on your system, you can launch
it straight from the build tree@footnote{The @option{-E} flag to
@command{sudo} guarantees that @code{GUILE_LOAD_PATH} is correctly set such
that @command{guix-daemon} and the tools it uses can find the Guile modules
they need.}:

@example
$ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild
@end example

O script @command{pre-inst-env} configura todas as variáveis de ambiente
necessárias para prover suporte a isso, incluindo @env{PATH} e
@env{GUILE_LOAD_PATH}.

Observe que @command{./pre-inst-env guix pull} @emph{não} atualiza a área de
fontes local; ele simplesmente atualiza o link simbólico
@file{~/.config/guix/current} (@pxref{Invocando guix pull}). Execute
@command{git pull} em vez disso, se você quiser atualizar sua árvore de
fontes local.


@node A configuração perfeita
@section A configuração perfeita

The Perfect Setup to hack on Guix is basically the perfect setup used for
Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile Reference
Manual}).  First, you need more than an editor, you need
@url{https://www.gnu.org/software/emacs, Emacs}, empowered by the wonderful
@url{https://nongnu.org/geiser/, Geiser}.  To set that up, run:

@example
guix package -i emacs guile emacs-geiser
@end example

O Geiser permite um desenvolvimento interativo e incremental de dentro do
Emacs: compilação e avaliação de código de dentro dos buffers, acesso à
documentação on-line (docstrings), completação sensível ao contexto,
@kbd{M-.} para pular para uma definição de objeto, um REPL para tentar seu
código e muito mais (@pxref{Introdução ,,, geiser, Manual de usuário do
Geiser}). Para um desenvolvimento prático do Guix, certifique-se de aumentar
o caminho de carregamento do Guile para que ele encontre os arquivos de
origem do seu checkout:

@lisp
;; @r{Presumindo que o checkout do Guix está em ~/src/guix.}
(with-eval-after-load 'geiser-guile
  (add-to-list 'geiser-guile-load-path "~/src/guix"))
@end lisp

To actually edit the code, Emacs already has a neat Scheme mode.  But in
addition to that, you must not miss
@url{https://www.emacswiki.org/emacs/ParEdit, Paredit}.  It provides
facilities to directly operate on the syntax tree, such as raising an
s-expression or wrapping it, swallowing or rejecting the following
s-expression, etc.

@cindex trechos de código
@cindex modelos
@cindex reduzindo boilerplate
We also provide templates for common git commit messages and package
definitions in the @file{etc/snippets} directory.  These templates can be
used with @url{https://joaotavora.github.io/yasnippet/, YASnippet} to expand
short trigger strings to interactive text snippets.  You may want to add the
snippets directory to the @var{yas-snippet-dirs} variable in Emacs.

@lisp
;; @r{Presumindo que o checkout do Guix está em ~/src/guix.}
(with-eval-after-load 'yasnippet
  (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets"))
@end lisp

Os trechos de mensagens de commit dependem de @url{https://magit.vc/, Magit}
para exibir arquivos "staged". Ao editar uma mensagem de commit, digite
@code{add} seguido por @kbd{TAB} para inserir um modelo de mensagem de
commit para adicionar um pacote; digite @code{update} seguido por @kbd{TAB}
para inserir um modelo para atualizar um pacote; digite @code{https} seguido
por @kbd{TAB} para inserir um modelo para alterar a URI da página inicial de
um pacote para HTTPS.

O trecho principal para @code{scheme-mode} é acionado digitando
@code{package ...} seguido de @kbd{TAB}. Esse trecho também insere a string
de acionamento @code{origin...}, que pode ser expandida ainda mais. O trecho
@code{origin}, por sua vez, pode inserir outras strings acionadoras que
terminam em @code{...}, que também podem ser expandidas.

@cindex insert or update copyright
@cindex @code{M-x guix-copyright}
@cindex @code{M-x copyright-update}
We additionally provide insertion and automatic update of a copyright in
@file{etc/copyright.el}.  You may want to set your full name, mail, and load
a file.

@lisp
(setq user-full-name "Alice Doe")
(setq user-mail-address "alice@@mail.org")
;; @r{Assuming the Guix checkout is in ~/src/guix.}
(load-file "~/src/guix/etc/copyright.el")
@end lisp

To insert a copyright at the current line invoke @code{M-x guix-copyright}.

To update a copyright you need to specify a @code{copyright-names-regexp}.

@lisp
(setq copyright-names-regexp
      (format "%s <%s>" user-full-name user-mail-address))
@end lisp

You can check if your copyright is up to date by evaluating @code{M-x
copyright-update}.  If you want to do it automatically after each buffer
save then add @code{(add-hook 'after-save-hook 'copyright-update)} in Emacs.

@node Diretrizes de empacotamento
@section Diretrizes de empacotamento

@cindex pacotes, criação
A distribuição do GNU é incipiente e pode muito bem não ter alguns dos seus
pacotes favoritos. Esta seção descreve como você pode ajudar a fazer a
distribuição crescer.

Pacotes de software livre geralmente são distribuídos na forma de
@dfn{tarballs de código-fonte} -- geralmente arquivos @file{tar.gz} que
contêm todos os arquivos fonte. Adicionar um pacote à distribuição significa
essencialmente duas coisas: adicionar uma @dfn{receita} que descreve como
criar o pacote, incluindo uma lista de outros pacotes necessários para
compilá-lo e adicionar @dfn{metadados de pacote} junto com essa receita,
como uma descrição e informações de licenciamento.

No Guix, todas essas informações estão incorporadas em @dfn{configurações de
pacote}. As definições de pacote fornecem uma visão de alto nível do
pacote. Elas são escritas usando a sintaxe da linguagem de programação
Scheme; de fato, para cada pacote, definimos uma variável vinculada à
definição do pacote e exportamos essa variável de um módulo (@pxref{Módulos
de pacote}). No entanto, o conhecimento profundo de Scheme @emph{não} é um
pré-requisito para a criação de pacotes. Para mais informações sobre
definições de pacotes, @pxref{Definindo pacotes}.

Quando uma definição de pacote está em vigor, armazenada em um arquivo na
árvore de fontes do Guix, ela pode ser testada usando o comando
@command{guix build} (@pxref{Invocando guix build}). Por exemplo, supondo
que o novo pacote seja chamado @code{gnew}, você pode executar este comando
na árvore de construção do Guix (@pxref{Executando guix antes dele ser
instalado}):

@example
./pre-inst-env guix build gnew --keep-failed
@end example

O uso de @code{--keep-failed} facilita a depuração de falhas de compilação,
pois fornece acesso à árvore de compilação com falha. Outra opção útil da
linha de comando ao depurar é @code{--log-file}, para acessar o log de
compilação.

Se o pacote for desconhecido para o comando @command{guix}, pode ser que o
arquivo fonte contenha um erro de sintaxe ou não tenha uma cláusula
@code{define-public} para exportar a variável do pacote. Para descobrir
isso, você pode carregar o módulo do Guile para obter mais informações sobre
o erro real:

@example
./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
@end example

Once your package builds correctly, please send us a patch
(@pxref{Enviando patches}).  Well, if you need help, we will be happy to
help you too.  Once the patch is committed in the Guix repository, the new
package automatically gets built on the supported platforms by
@url{@value{SUBSTITUTE-URL}, our continuous integration system}.

@cindex substituidor
Os usuários podem obter a nova definição de pacote simplesmente executando
@command{guix pull} (@pxref{Invocando guix pull}). Quando o
@code{@value{SUBSTITUTE-SERVER}} terminar de compilar o pacote, a instalação
do pacote fará o download automático dos binários a partir daí
(@pxref{Substitutos}). O único lugar onde a intervenção humana é necessária
é para revisar e aplicar o patch.


@menu
* Liberdade de software::    O que pode ir na distribuição.
* Nomeando um pacote::       Que há em um nome?
* Números de versão::      Quando o nome não é suficiente.
* Sinopses e descrições::  Ajudando usuários a localizar o pacote certo.
* Snippets versus Phases::   Whether to use a snippet, or a build phase.
* Emacs Packages::           Your Elisp fix.
* Módulos Python::          Um toque de comédia britânica.
* Módulos Perl::            Pequenas pérolas.
* Pacotes Java::             Parada para o café.
* Rust Crates::              Beware of oxidation.
* Fontes::                   Vício em fontes.
@end menu

@node Liberdade de software
@subsection Liberdade de software

@c Adapted from http://www.gnu.org/philosophy/philosophy.html.
@cindex software livre
The GNU operating system has been developed so that users can have freedom
in their computing.  GNU is @dfn{free software}, meaning that users have the
@url{https://www.gnu.org/philosophy/free-sw.html,four essential freedoms}:
to run the program, to study and change the program in source code form, to
redistribute exact copies, and to distribute modified versions.  Packages
found in the GNU distribution provide only software that conveys these four
freedoms.

In addition, the GNU distribution follow the
@url{https://www.gnu.org/distros/free-system-distribution-guidelines.html,free
software distribution guidelines}.  Among other things, these guidelines
reject non-free firmware, recommendations of non-free software, and discuss
ways to deal with trademarks and patents.

Algumas fontes de pacotes upstream livres de outra forma contêm um
subconjunto pequeno e opcional que viola as diretrizes acima, por exemplo,
porque esse subconjunto é ele próprio um código não livre. Quando isso
acontece, os itens incorretos são removidos com patches ou trechos de código
apropriados no formato @code{origin} do pacote (@pxref{Definindo
pacotes}). Dessa forma, o @code{guix build --source} retorna a fonte
``lançada'' em vez da fonte upstream não modificada.


@node Nomeando um pacote
@subsection Nomeando um pacote

@cindex nome de pacote
A package actually has two names associated with it.  First, there is the
name of the @emph{Scheme variable}, the one following @code{define-public}.
By this name, the package can be made known in the Scheme code, for instance
as input to another package.  Second, there is the string in the @code{name}
field of a package definition.  This name is used by package management
commands such as @command{guix package} and @command{guix build}.

Ambos são geralmente iguais e correspondem à conversão em minúscula do nome
do projeto escolhido a montante, com os sublinhados substituídos por
hífenes. Por exemplo, o GNUnet está disponível como @code{gnunet} e SDL_net
como @code{sdl-net}.

A noteworthy exception to this rule is when the project name is only a
single character, or if an older maintained project with the same name
already exists---regardless of whether it has already been packaged for
Guix.  Use common sense to make such names unambiguous and meaningful.  For
example, Guix's package for the shell called ``s'' upstream is
@code{s-shell} and @emph{not} @code{s}.  Feel free to ask your fellow
hackers for inspiration.

Não adicionamos prefixos @code{lib} para pacotes de bibliotecas, a menos que
eles já façam parte do nome oficial do projeto. Mas @pxref{Módulos Python} e
@ref{Módulos Perl} para regras especiais relativas a módulos para as
linguagens Python e Perl.

Nomes de pacote de fontes são lidados de forma diferente. @xref{Fontes}.


@node Números de versão
@subsection Números de versão

@cindex versão de pacote
Geralmente, empacotamos apenas a versão mais recente de um determinado
projeto de software livre. Mas, às vezes, por exemplo, para versões
incompatíveis de bibliotecas, são necessárias duas (ou mais) versões do
mesmo pacote. Isso requer nomes de variáveis Scheme diferentes. Usamos o
nome como definido em @ref{Nomeando um pacote} para a versão mais recente;
as versões anteriores usam o mesmo nome, com o sufixo @code{-} e o menor
prefixo do número da versão que pode distinguir as duas versões.

O nome dentro da definição do pacote é o mesmo para todas as versões de um
pacote e não contém nenhum número de versão.

Por exemplo, as versões 2.24.20 e 3.9.12 do GTK podem ser empacotados da
seguinte forma:

@lisp
(define-public gtk+
  (package
    (name "gtk+")
    (version "3.9.12")
    ...))
(define-public gtk+-2
  (package
    (name "gtk+")
    (version "2.24.20")
    ...))
@end lisp
Se também quiséssemos GTK 3.8.2, este seria empacotado como
@lisp
(define-public gtk+-3.8
  (package
    (name "gtk+")
    (version "3.8.2")
    ...))
@end lisp

@c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
@c for a discussion of what follows.
@cindex número de versão, para snapshots de VCS
Ocasionalmente, empacotamos snapshots do sistema de controle de versão (VCS)
do upstream em vez de lançamentos formais. Isso deve permanecer excepcional,
porque cabe aos desenvolvedores upstream esclarecer qual é a versão
estável. No entanto, às vezes é necessário. Então, o que devemos colocar no
campo @code{version}?

Claramente, precisamos tornar o identificador de commit do snapshot VCS
visível na string de versão, mas também precisamos garantir que a string de
versão esteja aumentando monotonicamente para que o @command{pacote guix
--upgrade} possa determinar qual versão é mais recente. Como os
identificadores de commit, principalmente com o Git, não estão aumentando
monotonicamente, adicionamos um número de revisão que aumentamos cada vez
que atualizamos para um snapshot mais recente. A sequência da versão
resultante é assim:

@example
2.0.11-3.cabba9e
  ^    ^    ^
  |    |    `-- ID do commit do upstream
  |    |
  |    `--- revisão do pacote do Guix
  |
versão mais recente do upstream
@end example

It is a good idea to strip commit identifiers in the @code{version} field
to, say, 7 digits.  It avoids an aesthetic annoyance (assuming aesthetics
have a role to play here) as well as problems related to OS limits such as
the maximum shebang length (127 bytes for the Linux kernel).  It is best to
use the full commit identifiers in @code{origin}s, though, to avoid
ambiguities.  A typical package definition may look like this:

@lisp
(define meu-pacote
  (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
        (revision "1"))          ;revisão do pacote do Guix
    (package
      (version (git-version "0.9" revision commit))
      (source (origin
                (method git-fetch)
                (uri (git-reference
                      (url "git://example.org/meu-pacote.git")
                      (commit commit)))
                (sha256 (base32 "1mbikn@dots{}"))
                (file-name (git-file-name name version))))
      ;; @dots{}
      )))
@end lisp

@node Sinopses e descrições
@subsection Sinopses e descrições

@cindex descrição do pacote
@cindex sinopse do pacote
Como vimos anteriormente, cada pacote no GNU@tie{}Guix inclui uma sinopse e
uma descrição (@pxref{Definindo pacotes}). Sinopses e descrições são
importantes: são o que o @command{guix package --search} pesquisa e uma
informação crucial para ajudar os usuários a determinar se um determinado
pacote atende às suas necessidades. Consequentemente, os empacotadores devem
prestar atenção ao que entra neles.

As sinopses devem começar com uma letra maiúscula e não devem terminar com
um ponto. Elas não devem começar com ``a'' ou ``the'', que geralmente não
traz nada; por exemplo, prefira ``Tool-frobbing tool'' em vez de ``A tool
that frobs files''. A sinopse deve dizer o que é o pacote -- por exemplo,
``Core GNU utilities (file, text, shell)'' -- ou para que é usado -- por
exemplo, a sinopse do GNU@tie{}grep é ``Print lines matching a pattern''.

Lembre-se de que a sinopse deve ser significativa para um público muito
amplo. Por exemplo, ``Manipulate alignments in the SAM format'' pode fazer
sentido para um pesquisador experiente em bioinformática, mas pode ser
bastante inútil ou até enganoso para um público não especializado. É uma boa
ideia apresentar uma sinopse que dê uma ideia do domínio do aplicativo do
pacote. Neste exemplo, isso pode fornecer algo como ``Manipulate nucleotide
sequence alignments'', o que, esperançosamente, dá ao usuário uma melhor
ideia de se é isso que eles estão procurando.

Descrições devem levar entre cinco e dez linhas. Use sentenças completas e
evite usar acrônimos sem primeiro apresentá-los. Por favor, evite frases de
marketing como ``inovação mundial'', ``força industrial'' e ``próxima
geração'', e evite superlativos como ``a mais avançada'' -- eles não ajudam
o usuário procurando por um pacote e podem atém parece suspeito. Em vez
idsso, tente se ater aos fatos, mencionando casos de uso e recursos.

@cindex Marcação Texinfo, em descrições de pacote
Descrições podem incluir marcação Texinfo, a qual é útil para apresentar
adornos como @code{@@code} ou @code{@@dfn}, listas não numeradas ou
hiperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}). Porém, você  deve ter
cuidado ao usar alguns caracteres, por exemplo @samp{@@} e chaves, que são
caracteres especiais básicos no Texinfo (@pxref{Special Characters,,,
texinfo, GNU Texinfo}). Interfaces de usuário, como @command{guix package
--show}, cuidam de renderizá-las adequadamente.

Synopses and descriptions are translated by volunteers
@uref{https://translate.fedoraproject.org/projects/guix/packages, at
Weblate} so that as many users as possible can read them in their native
language.  User interfaces search them and display them in the language
specified by the current locale.

Para permitir que @command{xgettext} extrai-as com strings traduzíveis, as
sinopses e descrições @emph{devem ser strings literais}. Isso significa que
você não pode usar @code{string-append} ou @code{format} para construir
essas strings:

@lisp
(package
  ;; @dots{}
  (synopsis "Isso é traduzível")
  (description (string-append "Isso " "*não*" " é traduzível.")))
@end lisp

Tradução é muito trabalhoso, então, como empacotador, por favor, tenha ainda
mais atenção às suas sinopses e descrições, pois cada alteração pode
implicar em trabalho adicional para tradutores. Para ajudá-loas, é possível
tornar recomendações ou instruções visíveis inserindo comentários especiais
como esse (@pxref{xgettext Invocation,,, gettext, GNU Gettext}):

@lisp
;; TRANSLATORS: "X11 resize-and-rotate" should not be translated.
(description "ARandR is designed to provide a simple visual front end
for the X11 resize-and-rotate (RandR) extension. @dots{}")
@end lisp

@node Snippets versus Phases
@subsection Snippets versus Phases

@cindex snippets, when to use
The boundary between using an origin snippet versus a build phase to modify
the sources of a package can be elusive.  Origin snippets are typically used
to remove unwanted files such as bundled libraries, nonfree sources, or to
apply simple substitutions.  The source derived from an origin should
produce a source that can be used to build the package on any system that
the upstream package supports (i.e., act as the corresponding source).  In
particular, origin snippets must not embed store items in the sources; such
patching should rather be done using build phases.  Refer to the
@code{origin} record documentation for more information (@pxref{Referência do origin}).

@node Emacs Packages
@subsection Emacs Packages

@cindex emacs, packaging
@cindex elisp, packaging
Emacs packages should preferably use the Emacs build system
(@pxref{emacs-build-system}), for uniformity and the benefits provided by
its build phases, such as the auto-generation of the autoloads file and the
byte compilation of the sources.  Because there is no standardized way to
run a test suite for Emacs packages, tests are disabled by default.  When a
test suite is available, it should be enabled by setting the @code{#:tests?}
argument to @code{#true}.  By default, the command to run the test is
@command{make check}, but any command can be specified via the
@code{#:test-command} argument.  The @code{#:test-command} argument expects
a list containing a command and its arguments, to be invoked during the
@code{check} phase.

The Elisp dependencies of Emacs packages are typically provided as
@code{propagated-inputs} when required at run time.  As for other packages,
build or test dependencies should be specified as @code{native-inputs}.

Emacs packages sometimes depend on resources directories that should be
installed along the Elisp files.  The @code{#:include} argument can be used
for that purpose, by specifying a list of regexps to match.  The best
practice when using the @code{#:include} argument is to extend rather than
override its default value (accessible via the @code{%default-include}
variable).  As an example, a yasnippet extension package typically include a
@file{snippets} directory, which could be copied to the installation
directory using:

@lisp
#:include (cons "^snippets/" %default-include))
@end lisp

When encountering problems, it is wise to check for the presence of the
@code{Package-Requires} extension header in the package main source file,
and whether any dependencies and their versions listed therein are
satisfied.

@node Módulos Python
@subsection Módulos Python

@cindex python
Atualmente empacotamos Python 2 e Python 3, sob os nomes de variável Scheme
@code{python-2} e @code{python} conforme explicado em @ref{Números de
versão}.  Para evitar confusão e conflitos de nomes com outras linguagens de
programação, parece desejável que o nome de um pacote para um módulo Python
contenha a palavra @code{python}.

Some modules are compatible with only one version of Python, others with
both.  If the package Foo is compiled with Python 3, we name it
@code{python-foo}.  If it is compiled with Python 2, we name it
@code{python2-foo}.  Packages should be added when they are necessary; we
don't add Python 2 variants of the package unless we are going to use them.

Se um projeto já contém a palavra @code{python}, nós a descartamos; por
exemplo, o módulo python-dateutil é empacotado sob os nomes
@code{python-dateutil} e @code{python2-dateutil}. Se o nome do projeto
começa com @code{py} (p.ex., @code{pytz}), nós o mantemos e o prefixamos
conforme descrito acima.

@subsubsection Especificando dependências
@cindex entradas, para pacotes Python

Informações de dependências para pacotes Python estão geralmente disponíveis
na árvore de fonte do pacote, com vários graus de precisão: no arquivo
@file{setup.py}, no @file{requirements.txt} ou no @file{tox.ini}.

Sua missão, ao escrever uma receita para um pacote Python, é mapear essas
dependências para o tipo apropriado de ``entrada'' (@pxref{Referência do
package, inputs}). Apesar do importador do @code{pypi} normalmente fazer um
bom trabalho (@pxref{Invocando guix import}), você pode se interessar em
verificar a lista de verificação a seguir para determinar qual dependência
vai onde.

@itemize

@item
Atualmente empacotamos Python 2 com @code{setuptools} e @code{pip} instalado
como Python 3.4 tem por padrão. Então, você não precisa especificar nenhum
deles como entrada. @command{guix lint} vai avisar você se precisar.

@item
Dependências de Python necessárias em tempo de execução vão em
@code{propagated-inputs}. Elas geralmente são definidas com a palavra-chave
@code{install_requires} em @file{setup.py} ou no arquivo
@file{requirements.txt}.

@item
Pacotes Python necessários apenas em tempo de compilação -- p.ex., aqueles
listados com a palavra-chave @code{setup_requires} em @file{setup.py} -- ou
apenas para teste -- p.ex., aqueles em @code{tests_require} -- vão em
@code{native-inputs}. O motivo é que (1) eles não precisam ser propagados
porque não são necessários em tempo de execução e (2) em um contexto de
compilação cruzada, é a entrada ``nativa'' que nós queremos.

Exemplos são os frameworks de teste @code{pytest}, @code{mock} e
@code{nose}. É claro, se qualquer um desses pacotes também for necessário em
tempo de compilação, ele precisa ir para @code{propagated-inputs}.

@item
Qualquer coisa que não encaixar nas categorias anteriores vai para
@code{inputs}. Por exemplo, programas ou bibliotecas C necessárias para
compilar pacotes Python contendo extensões C.

@item
Se um pacote Python tem dependências opcionais (@code{extras_require}), fica
a seu critério adicioná-las ou não, com base na sua proporção de
utilidade/sobrecarga (@pxref{Enviando patches, @command{guix size}}).

@end itemize


@node Módulos Perl
@subsection Módulos Perl

@cindex perl
Os programas Perl próprios são nomeados como qualquer outro pacote, usando o
nome upstream em letras minúsculas. Para pacotes Perl que contêm uma única
classe, usamos o nome da classe em letras minúsculas, substituímos todas as
ocorrências de @code{::} por traços e precede o prefixo
@code{perl-}. Portanto, a classe @code{XML::Parser} se torna
@code{perl-xml-parser}. Módulos contendo várias classes mantêm seu nome
upstream em minúsculas e também são precedidos por @code{perl-}. Esses
módulos tendem a ter a palavra @code{perl} em algum lugar do nome, que é
descartada em favor do prefixo. Por exemplo, @code{libwww-perl} se torna
@code{perl-libwww}.


@node Pacotes Java
@subsection Pacotes Java

@cindex java
Os programas Java próprios são nomeados como qualquer outro pacote, usando o
nome do upstream em letras minúsculas.

Para evitar confusão e conflitos de nomes com outras linguagens de
programação, é desejável que o nome de um pacote para um pacote Java seja
prefixado com @code{java-}. Se um projeto já contém a palavra @code{java},
descartamos isso; por exemplo, o pacote @code{ngsjava} é empacotado com o
nome @code{java-ngs}.

Para pacotes Java que contêm uma única classe ou uma pequena hierarquia de
classes, usamos o nome da classe em letras minúsculas, substitua todas as
ocorrências de @code{.} por traços e acrescente o prefixo
@code{java-}. Assim, a classe @code{apache.commons.cli} se torna o pacote
@code{java-apache-commons-cli}.


@node Rust Crates
@subsection Rust Crates

@cindex rust
Rust programs standing for themselves are named as any other package, using
the lowercase upstream name.

To prevent namespace collisions we prefix all other Rust packages with the
@code{rust-} prefix.  The name should be changed to lowercase as appropriate
and dashes should remain in place.

In the rust ecosystem it is common for multiple incompatible versions of a
package to be used at any given time, so all package definitions should have
a versioned suffix.  The versioned suffix is the left-most non-zero digit
(and any leading zeros, of course).  This follows the ``caret'' version
scheme intended by Cargo.  Examples@: @code{rust-clap-2},
@code{rust-rand-0.6}.

Because of the difficulty in reusing rust packages as pre-compiled inputs
for other packages the Cargo build system (@pxref{Sistemas de compilação,
@code{cargo-build-system}}) presents the @code{#:cargo-inputs} and
@code{cargo-development-inputs} keywords as build system arguments.  It
would be helpful to think of these as similar to @code{propagated-inputs}
and @code{native-inputs}.  Rust @code{dependencies} and
@code{build-dependencies} should go in @code{#:cargo-inputs}, and
@code{dev-dependencies} should go in @code{#:cargo-development-inputs}.  If
a Rust package links to other libraries then the standard placement in
@code{inputs} and the like should be used.

Care should be taken to ensure the correct version of dependencies are used;
to this end we try to refrain from skipping the tests or using
@code{#:skip-build?} when possible.  Of course this is not always possible,
as the package may be developed for a different Operating System, depend on
features from the Nightly Rust compiler, or the test suite may have
atrophied since it was released.


@node Fontes
@subsection Fontes

@cindex fontes
Para fontes que geralmente não são instaladas por um usuário para fins de
digitação ou que são distribuídas como parte de um pacote de software maior,
contamos com as regras gerais de empacotamento de software; por exemplo,
isso se aplica às fontes entregues como parte do sistema X.Org ou às fontes
que fazem parte do TeX Live.

Para facilitar a busca de fontes por um usuário, os nomes de outros pacotes
contendo apenas fontes são compilados da seguinte maneira, independentemente
do nome do pacote upstream.

O nome de um pacote que contém apenas uma família de fontes começa com
@code{font-}; é seguido pelo nome da fundição e um traço @code{-} se a
fundição for conhecida e o nome da família da fonte, em que os espaços são
substituídos por hífenes (e, como sempre, todas as letras maiúsculas são
transformadas em minúsculas). Por exemplo, a família de fontes Gentium da
SIL é empacotada com o nome @code{font-sil-gentium}.

Para um pacote que contém várias famílias de fontes, o nome da coleção é
usado no lugar do nome da família de fontes. Por exemplo, as fontes
Liberation consistem em três famílias, Liberation Sans, Liberation Serif e
Liberation Mono. Eles podem ser empacotados separadamente com os nomes
@code{font-liberation-sans} e assim por diante; mas como eles são
distribuídos juntos com um nome comum, preferimos agrupá-los como
@code{font-liberation}.

No caso de vários formatos da mesma família ou coleção de fontes serem
empacotados separadamente, um formato abreviado do formato, precedido por um
traço, é adicionado ao nome do pacote. Usamos @code{-ttf} para fontes
TrueType, @code{-otf} para fontes OpenType e @code{-type1} para fontes
PostScript Type 1.


@node Estilo de código
@section Estilo de código

Em geral, nosso código segue os Padrões de Codificação GNU (@pxref{Top ,,,
standards, GNU Coding Standards}). No entanto, eles não dizem muito sobre
Scheme, então aqui estão algumas regras adicionais.

@menu
* Paradigma de programação::  Como compor seus elementos.
* Módulos::                 Onde armazenar seu código?
* Tipos de dados e correspondência de padrão::  Implementação de 
                                                    estruturas de dados.
* Formatação de código::  Convenções de escrita.
@end menu

@node Paradigma de programação
@subsection Paradigma de programação

O código Scheme no Guix é escrito em um estilo puramente funcional. Uma
exceção é o código que envolve entrada/saída e procedimentos que implementam
conceitos de baixo nível, como o procedimento @code{memoize}.

@node Módulos
@subsection Módulos

Os módulos de Guile que devem ser usados no lado do compilador devem residir
no espaço de nomes @code{(guix build @dots{})}. Eles não devem fazer
referência a outros módulos Guix ou GNU. No entanto, é aceitável que um
módulo no lado do ``hospedeiro'' use um módulo do lado do compilador.

Módulos que lidam com o sistema GNU mais amplo devem estar no espaço de nome
@code{(gnu @dots{})} em vez de @code{(guix @dots{})}.

@node Tipos de dados e correspondência de padrão
@subsection Tipos de dados e correspondência de padrão

A tendência no Lisp clássico é usar listas para representar tudo e, em
seguida, pesquisá-las ``à mão'' usando @code{car}, @code{cdr}, @code{cadr} e
co. Existem vários problemas com esse estilo, notadamente o fato de que é
difícil de ler, propenso a erros e um obstáculo para os relatórios de erros
de tipos adequados.

Guix code should define appropriate data types (for instance, using
@code{define-record-type*}) rather than abuse lists.  In addition, it should
use pattern matching, via Guile’s @code{(ice-9 match)} module, especially
when matching lists (@pxref{Pattern Matching,,, guile, GNU Guile Reference
Manual}).

@node Formatação de código
@subsection Formatação de código

@cindex formatação de código
@cindex estilo de codificação
When writing Scheme code, we follow common wisdom among Scheme programmers.
In general, we follow the
@url{https://mumble.net/~campbell/scheme/style.txt, Riastradh's Lisp Style
Rules}.  This document happens to describe the conventions mostly used in
Guile’s code too.  It is very thoughtful and well written, so please do read
it.

Alguns formulários especiais introduzidos no Guix, como a macro
@code{substitute*}, possuem regras especiais de recuo. Estes são definidos
no arquivo @file{.dir-locals.el}, que o Emacs usa automaticamente. Observe
também que o Emacs-Guix fornece o modo @code{guix-devel-mode} que recua e
destaca o código Guix corretamente (@pxref{Development ,,, emacs-guix, O
manual de referência do Emacs-Guix}).

@cindex recuo, de código
@cindex formatação, de código
Se você não usa o Emacs, por favor, certifique-se que o seu editor conhece
estas regras. Para recuar automaticamente uma definição de pacote, você
também pode executar:

@example
./etc/indent-code.el gnu/packages/@var{arquivo}.scm @var{pacote}
@end example

@noindent
Isso automaticamente recua a definição de @var{pacote} em
@file{gnu/packages/@var{arquivo}.scm} executando o Emacs no modo em
lote. Para recuar um arquivo inteiro, omita o segundo argumento:

@example
./etc/indent-code.el gnu/services/@var{arquivo}.scm
@end example

@cindex Vim, edição de código Scheme
Se você estiver editando código com o Vim, recomendamos que execute
@code{:set autoindent} para que seu código seja automaticamente recuado na
medida em que você digita. Além disso, o
@uref{https://www.vim.org/scripts/script.php?script_id=3998,
@code{paredit.vim}} pode ajudá-lo a lidar com todos esses parênteses.

Nós exigimos que todos os procedimentos de nível superior carreguem uma
docstring. Porém, este requisito pode ser relaxado para procedimentos
privados simples no espaço de nomes @code{(guix build @dots{})}.

Os procedimentos não devem ter mais de quatro parâmetros posicionais. Use os
parâmetros de palavra-chave para procedimentos que levam mais de quatro
parâmetros.


@node Enviando patches
@section 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 @code{git format-patch}
sent to the @email{guix-patches@@gnu.org} mailing list.  Seasoned Guix
developers may also want to look at the section on commit access
(@pxref{Commit Access}).

This mailing list is backed by a Debbugs instance, which allows us to keep
track of submissions (@pxref{Tracking Bugs and Patches}).  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
@code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is the tracking number
(@pxref{Enviando uma série de patches}).

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

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

@enumerate
@item
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 @code{gpg --verify}.

@item
Reserve algum tempo para fornecer uma sinopse e descrição adequadas para o
pacote. @xref{Sinopses e descrições}, para algumas diretrizes.

@item
Execute @code{guix lint @var{pacote}}, sendo @var{pacote} o nome do pacote
novo ou modificado e corrija quaisquer erros que forem relatados
(@pxref{Invocando guix lint}).

@item
Certifique-se de que o pacote compila em sua plataforma, usando @code{guix
build @var{pacote}}.

@item
Recomendamos que você também tente compilar o pacote em outras plataformas
suportadas. Como você pode não ter acesso às plataformas de hardware reais,
recomendamos o uso do @code{qemu-binfmt-service-type} para emulá-las. Para
habilitar isso, adicione o seguinte serviço à lista de serviços na sua
configuração @code{operating-system}:

@lisp
(service qemu-binfmt-service-type
 (qemu-binfmt-configuration
   (platforms (lookup-qemu-platforms "arm" "aarch64"))
@end lisp

Então, reconfigure seu sistema.

Você pode criar pacotes para plataformas diferentes especificando a opção
@code{--system}. Por exemplo, para compilar o pacote "hello" para as
arquiteturas armhf, aarch64 ou mips64, você executaria os seguintes
comandos, respectivamente:
@example
guix build --system=armhf-linux --rounds=2 hello
guix build --system=aarch64-linux --rounds=2 hello
@end example

@item
@cindex incorporando
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.

@item
Take a look at the profile reported by @command{guix size} (@pxref{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 (@pxref{Pacotes com múltiplas saídas}), and which optional
dependencies should be used.  In particular, avoid adding @code{texlive} as
a dependency: because of its extreme size, use the @code{texlive-tiny}
package or @code{texlive-union} procedure instead.

@item
Para alterações importantes, verifique se o pacote dependente (se aplicável)
não é afetado pela alteração; @code{guix refresh --list-dependent
@var{pacote}} ajudará você a fazer isso (@pxref{Invocando guix refresh}).

@c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>.
@cindex estratégia de ramificação
@cindex estratégia de agendamento de recompilação
Dependendo do número de pacotes dependentes e, portanto, da quantidade de
recompilação induzida, os commits vão para diferentes ramos, ao longo das
seguintes linhas:

@table @asis
@item 300 pacotes dependentes ou menos
Ramo @code{master} (alterações não disruptivas).

@item between 300 and 1,800 dependent packages
@code{staging} branch (non-disruptive changes).  This branch is intended to
be merged in @code{master} every 6 weeks or so.  Topical changes (e.g., an
update of the GNOME stack) can instead go to a specific branch (say,
@code{gnome-updates}).

@item more than 1,800 dependent packages
@code{core-updates} branch (may include major and potentially disruptive
changes).  This branch is intended to be merged in @code{master} every 6
months or so.
@end table

All these branches are @uref{@value{SUBSTITUTE-URL}, tracked by our build
farm} and merged into @code{master} once everything has been successfully
built.  This allows us to fix issues before they hit users, and to reduce
the window during which pre-built binaries are not available.

@c TODO: It would be good with badges on the website that tracks these
@c branches.  Or maybe even a status page.
When we decide to start building the @code{staging} or @code{core-updates}
branches, they will be forked and renamed with the suffix @code{-frozen}, at
which time only bug fixes may be pushed to the frozen branches.  The
@code{core-updates} and @code{staging} branches will remain open to accept
patches for the next cycle.  Please ask on the mailing list or IRC if unsure
where to place a patch.

@item
@cindex determinismo, de processos de compilação
@cindex compilações reproduzíveis, verificação
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 (@pxref{Invocando guix build}):

@example
guix build --rounds=2 meu-pacote
@end example

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 @command{guix challenge} (@pxref{Invocando guix
challenge}). Você pode executá-lo uma vez que o pacote se tenha sido feito o
commit e compilação por @code{SUBSTITUTE-SERVER} para verificar se obtém o
mesmo resultado que você fez. Melhor ainda: encontre outra máquina que possa
compilá-lo e executar @command{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 @code{uname} ou arquivos de @file{/proc}.

@item
Ao escrever documentação, por favor, use palavras de gênero neutras ao se
referir a pessoas, como @uref{https://en.wikipedia.org/wiki/Singular_they,
singular ``they''@comma{} ``their'' @comma{} ``them''}, e assim por diante.

@item
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.

@item
Siga nossas regras de formatação de código, possivelmente executando o
script @command{etc/indent-code.el} para fazer isso automaticamente para
você (@pxref{Formatação de código}).

@item
Quando possível, use espelhos no URL fonte (@pxref{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 @command{name} no URL: não é muito útil e se o nome mudar, o URL
provavelmente estará errado.

@item
Check if Guix builds (@pxref{Compilando do git}) and address the warnings,
especially those about use of undefined symbols.

@item
Make sure your changes do not break Guix and simulate a @code{guix pull}
with:
@example
guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master
@end example

@end enumerate

When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as a
subject, if your patch is to be applied on a branch other than
@code{master}, say @code{core-updates}, specify it in the subject like
@samp{[PATCH core-updates] @dots{}}.  You may use your email client or the
@command{git send-email} command (@pxref{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.

Quando um erro for resolvido, feche o tópico enviando um e-mail para
@email{@var{NNN}-done@@debbugs.gnu.org}.

@unnumberedsubsec Enviando uma série de patches
@anchor{Enviando uma série de patches}
@cindex série de patches
@cindex @code{git send-email}
@cindex @code{git-send-email}

@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
When sending a patch series (e.g., using @code{git send-email}), please
first send one message to @email{guix-patches@@gnu.org}, and then send
subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure they
are kept together.  See @uref{https://debbugs.gnu.org/Advanced.html, the
Debbugs documentation} for more information.  You can install @command{git
send-email} with @command{guix install git:send-email}.

@node Tracking Bugs and Patches
@section Tracking Bugs and Patches

@cindex bug reports, tracking
@cindex patch submissions, tracking
@cindex issue tracking
@cindex Debbugs, issue tracking system
Bug reports and patch submissions are currently tracked using the Debbugs
instance at @uref{https://bugs.gnu.org}.  Bug reports are filed against the
@code{guix} ``package'' (in Debbugs parlance), by sending email to
@email{bug-guix@@gnu.org}, while patch submissions are filed against the
@code{guix-patches} package by sending email to
@email{guix-patches@@gnu.org} (@pxref{Enviando patches}).

A web interface (actually @emph{two} web interfaces!) are available to
browse issues:

@itemize
@item
@url{https://issues.guix.gnu.org} provides a pleasant interface@footnote{The
web interface at @url{https://issues.guix.gnu.org} is powered by Mumi, a
nice piece of software written in Guile, and you can help! See
@url{https://git.elephly.net/gitweb.cgi?p=software/mumi.git}.} to browse bug
reports and patches, and to participate in discussions;
@item
@url{https://bugs.gnu.org/guix} lists bug reports;
@item
@url{https://bugs.gnu.org/guix-patches} lists patch submissions.
@end itemize

To view discussions related to issue number @var{n}, go to
@indicateurl{https://issues.guix.gnu.org/@var{n}} or
@indicateurl{https://bugs.gnu.org/@var{n}}.

If you use Emacs, you may find it more convenient to interact with issues
using @file{debbugs.el}, which you can install with:

@example
guix install emacs-debbugs
@end example

For example, to list all open issues on @code{guix-patches}, hit:

@example
@kbd{C-u} @kbd{M-x} debbugs-gnu @kbd{RET} @kbd{RET} guix-patches @kbd{RET} n y
@end example

@xref{Top,,, debbugs-ug, Debbugs User Guide}, for more information on this
nifty tool!

@node Commit Access
@section Commit Access

@cindex commit access, for developers
For frequent contributors, having write access to the repository is
convenient.  When you deem it necessary, consider applying for commit access
by following these steps:

@enumerate
@item
Find three committers who would vouch for you.  You can view the list of
committers at
@url{https://savannah.gnu.org/project/memberlist.php?group=guix}.  Each of
them should email a statement to @email{guix-maintainers@@gnu.org} (a
private alias for the collective of maintainers), signed with their OpenPGP
key.

Committers are expected to have had some interactions with you as a
contributor and to be able to judge whether you are sufficiently familiar
with the project's practices.  It is @emph{not} a judgment on the value of
your work, so a refusal should rather be interpreted as ``let's try again
later''.

@item
Send @email{guix-maintainers@@gnu.org} a message stating your intent,
listing the three committers who support your application, signed with the
OpenPGP key you will use to sign commits, and giving its fingerprint (see
below).  See @uref{https://emailselfdefense.fsf.org/en/}, for an
introduction to public-key cryptography with GnuPG.

@c See <https://sha-mbles.github.io/>.
Set up GnuPG such that it never uses the SHA1 hash algorithm for digital
signatures, which is known to be unsafe since 2019, for instance by adding
the following line to @file{~/.gnupg/gpg.conf} (@pxref{GPG Esoteric
Options,,, gnupg, The GNU Privacy Guard Manual}):

@example
digest-algo sha512
@end example

@item
Maintainers ultimately decide whether to grant you commit access, usually
following your referrals' recommendation.

@item
@cindex OpenPGP, signed commits
If and once you've been given access, please send a message to
@email{guix-devel@@gnu.org} to say so, again signed with the OpenPGP key you
will use to sign commits (do that before pushing your first commit).  That
way, everyone can notice and ensure you control that OpenPGP key.

@quotation Important
Before you can push for the first time, maintainers must:

@enumerate
@item
add your OpenPGP key to the @code{keyring} branch;
@item
add your OpenPGP fingerprint to the @file{.guix-authorizations} file of the
branch(es) you will commit to.
@end enumerate
@end quotation

@item
Make sure to read the rest of this section and... profit!
@end enumerate

@quotation Nota
Maintainers are happy to give commit access to people who have been
contributing for some time and have a track record---don't be shy and don't
underestimate your work!

However, note that the project is working towards a more automated patch
review and merging system, which, as a consequence, may lead us to have
fewer people with commit access to the main repository.  Stay tuned!
@end quotation

If you get commit access, please make sure to follow the policy below
(discussions of the policy can take place on @email{guix-devel@@gnu.org}).

Non-trivial patches should always be posted to @email{guix-patches@@gnu.org}
(trivial patches include fixing typos, etc.).  This mailing list fills the
patch-tracking database (@pxref{Tracking Bugs and Patches}).

For patches that just add a new package, and a simple one, it's OK to
commit, if you're confident (which means you successfully built it in a
chroot setup, and have done a reasonable copyright and license auditing).
Likewise for package upgrades, except upgrades that trigger a lot of
rebuilds (for example, upgrading GnuTLS or GLib).  We have a mailing list
for commit notifications (@email{guix-commits@@gnu.org}), so people can
notice.  Before pushing your changes, make sure to run @code{git pull
--rebase}.

All commits that are pushed to the central repository on Savannah must be
signed with an OpenPGP key, and the public key should be uploaded to your
user account on Savannah and to public key servers, such as
@code{keys.openpgp.org}.  To configure Git to automatically sign commits,
run:

@example
git config commit.gpgsign true
git config user.signingkey CABBA6EA1DC0FF33
@end example

You can prevent yourself from accidentally pushing unsigned commits to
Savannah by using the pre-push Git hook called located at
@file{etc/git/pre-push}:

@example
cp etc/git/pre-push .git/hooks/pre-push
@end example

When pushing a commit on behalf of somebody else, please add a
@code{Signed-off-by} line at the end of the commit log message---e.g., with
@command{git am --signoff}.  This improves tracking of who did what.

When adding channel news entries (@pxref{Canais, Writing Channel News}),
make sure they are well-formed by running the following command right before
pushing:

@example
make check-channel-news
@end example

For anything else, please post to @email{guix-patches@@gnu.org} and leave
time for a review, without committing anything (@pxref{Enviando patches}).  If you didn’t receive any reply after two weeks, and if you're
confident, it's OK to commit.

That last part is subject to being adjusted, allowing individuals to commit
directly on non-controversial changes on parts they’re familiar with.

In order to reduce the possibility of mistakes, committers will have their
Savannah account removed from the Guix Savannah project and their key
removed from @file{.guix-authorizations} after 12 months of inactivity; they
can ask to regain commit access by emailing the maintainers, without going
through the vouching process.

One last thing: the project keeps moving forward because committers not only
push their own awesome changes, but also offer some of their time
@emph{reviewing} and pushing other people's changes.  As a committer, you're
welcome to use your expertise and commit rights to help other contributors,
too!

@node Updating the Guix Package
@section Updating the Guix Package

@cindex update-guix-package, updating the guix package
It is sometimes desirable to update the @code{guix} package itself (the
package defined in @code{(gnu packages package-management)}), for example to
make new daemon features available for use by the @code{guix-service-type}
service type.  In order to simplify this task, the following command can be
used:

@example
make update-guix-package
@end example

The @code{update-guix-package} make target will use the last known
@emph{commit} corresponding to @code{HEAD} in your Guix checkout, compute
the hash of the Guix sources corresponding to that commit and update the
@code{commit}, @code{revision} and hash of the @code{guix} package
definition.

To validate that the updated @code{guix} package hashes are correct and that
it can be built successfully, the following command can be run from the
directory of your Guix checkout:

@example
./pre-inst-env guix build guix
@end example

To guard against accidentally updating the @code{guix} package to a commit
that others can't refer to, a check is made that the commit used has already
been pushed to the Savannah-hosted Guix git repository.

This check can be disabled, @emph{at your own peril}, by setting the
@code{GUIX_ALLOW_ME_TO_USE_PRIVATE_COMMIT} environment variable.  When this
variable is set, the updated package source is also added to the store.
This is used as part of the release process of Guix.
