@node Contribuir
@chapter Contribuir

Este proyecto es un esfuerzo colaborativo, y ¡necesitamos su ayuda para que
crezca! Por favor, contacte con nosotros en @email{guix-devel@@gnu.org} y en
@code{#guix} en la red IRC Libera Chat. Estamos abiertos a ideas, informes
de errores, parches y cualquier cosa que pueda ser de ayuda para el
proyecto. Especialmente se agradece ayuda con la creación de paquetes
(@pxref{Pautas de empaquetamiento}).

@cindex código de conducta, de contribuidoras
@cindex acuerdo de contribución
Queremos proporcionar un entorno cálido, amistoso y libre de acoso, para que
cualquiera pueda contribuir al máximo de sus capacidades. Para este fin
nuestro proyecto usa un ``Acuerdo de Contribución'', que fue adaptado de
@url{https://contributor-coventant.org}. Se puede encontrar una versión
local en el archivo @file{CODE-OF-CONDUCT} del árbol de fuentes.

Las contribuidoras no están obligadas a usar su nombre legal en los parches
ni en la comunicación on-line; pueden usar cualquier nombre o seudónimo de
su elección.

@menu
* Construcción desde Git::  Lo último y mejor.
* Ejecución de Guix antes de estar instalado::  Trucos de hacker.
* La configuración perfecta::  Las herramientas adecuadas.
* Pautas de empaquetamiento::  Crecimiento de la distribución.
* Estilo de codificación::  Higiene de la contribuidora.
* Envío de parches::        Comparta su trabajo.
* Seguimiento de errores y parches::  Mantenerlo todo organizado.
* Acceso al repositorio::    Subida de revisiones al repositorio oficial.
* Actualizar el paquete Guix::  Actualización de la definición del paquete 
                                  Guix.
* Writing Documentation::    Mejorar la documentación en GNU Guix.
* Traduciendo Guix::         Haga que Guix hable su lengua madre.
@end menu

@node Construcción desde Git
@section Construcción desde Git

Si quiere picar en el mismo Guix se recomienda usar la última versión del
repositorio Git:

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

@cindex identificación, de una copia de Guix
¿Cómo se puede asegurar de que ha obtenido una copia auténtica del
repositorio? Para ello ejecute @command{guix git authenticate},
proporcionando la revisión y la huella de OpenPGP de la @dfn{presentación
del canal} (@pxref{Invocación de 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
Esta orden termina con un código de salida cero cuando al finalizar
correctamente; o imprime un mensaje de error y sale con un código de salida
distinto a cero en otro caso.

Como puede ver, nos encontramos ante el problema del huevo y la gallina: es
necesario haber instalado Guix. Durante la instalación habitual del sistema
Guix (@pxref{Instalación del sistema}) o Guix sobre otra distribución
(@pxref{Instalación binaria}) debería verificar la firma de OpenPGP del
medio de instalación. Este paso es el primer eslabón de la cadena de
confianza.

El modo más fácil de preparar un entorno de desarrollo para Guix es, por
supuesto, ¡usando Guix! Las siguientes órdenes inician un nuevo intérprete
donde todas las dependencias y las variables de entorno apropiadas están
listas para picar código en Guix:

@example
guix shell -D guix --pure
@end example

@xref{Invoking guix shell}, para más información sobre este comando.

Si no puede usar Guix para construir Guix desde una copia de trabajo, son
necesarios los paquetes siguientes además de los mencionados en las
instrucciones de instalación (@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 (opcional)}.
@end itemize

En Guix se pueden añadir dependencias adicionales ejecutando en su lugar
@command{guix shell}:

@example
guix shell -D guix help2man git strace --pure
@end example

From there you can generate the build system infrastructure using Autoconf
and Automake:

@example
./bootstrap
@end example

Si se produce un error como el siguiente:

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

@noindent
probablemente significa que Autoconf no pudo encontrar el archivo pkg.m4,
que proporciona pkg-config. Asegúrese de que @file{pkg.m4} está
disponible. Lo mismo aplica para el conjunto de macros @file{guile.m4} que
proporciona Guile. Por ejemplo, si ha instalado Automake en
@file{/usr/local}, no va a buscar archivos @file{.m4} en
@file{/usr/share}. En ese caso tiene que ejecutar la siguiente orden:

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

@xref{Macro Search Path,,, automake, The GNU Automake Manual} para más
información.

Entonces, ejecute:

@example
./configure --localstatedir=/var
@end example

@noindent
... where @file{/var} is the normal @code{localstatedir} value (@pxref{El almacén}, for information about this).  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}.

Finalmente, puede construir Guix y, si se siente inclinado a ello, ejecutar
los tests (@pxref{Ejecución de la batería de pruebas}):

@example
make
make check
@end example

@noindent
If anything fails, take a look at installation instructions
(@pxref{Instalación}) or send a message to the @email{guix-devel@@gnu.org,
mailing list}.

De aquí en adelante, puede identificar todos las revisiones incluidas en su
copia ejecutando:

@example
make authenticate
@end example

La primera ejecución puede tardar varios minutos, pero las ejecuciones
siguientes son más rápidas.

O, cuando la configuración de su repositorio local Git no corresponda con la
predeterminada, puede proporcionar la referencia de la rama @code{keyring} a
través de la variable @code{GUIX_GIT_KEYRING}.  El ejemplo siguiente asume
que tiene configurado un servidor remoto de git llamado @samp{miremoto} que
apunta al repositorio oficial:

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

@quotation Nota
Se recomienda que ejecute @command{make authenticate} tras cada ejecución de
@command{git pull}. Así se asegura de que está recibiendo cambios válidos
del repositorio.
@end quotation

Después de actualizar el repositorio, @command{make} podría fallar con un
error similar al del ejemplo siguiente:

@example
error: fallo al cargar 'gnu/packages/dunst.scm':
ice-9/eval.scm:293:34: En el procedimiento abi-check: #<record-type <origin>>: registro ABI erróneo; se necesita recompilación
@end example

Esto significa que uno de los tipos de registro que Guix define (en este
ejemplo, el registro @code{origin}) ha cambiado, y todo guix necesita ser
recompilado para tener en cuenta ese cambio.  Para ello, ejecute
@command{make clean-go} seguido de @command{make}.

@node Ejecución de Guix antes de estar instalado
@section Ejecución de Guix antes de estar instalado

Para mantener un entorno de trabajo estable, encontrará útil probar los
cambios hechos en su copia de trabajo local sin instalarlos realmente. De
esa manera, puede distinguir entre su sombrero de ``usuaria final'' y el
traje de ``harapos''.

Para dicho fin, todas las herramientas de línea de comandos pueden ser
usadas incluso si no ha ejecutado @code{make install}. Para hacerlo, primero
necesita tener un entorno con todas las dependencias disponibles
(@pxref{Construcción desde Git}) y entonces añada al inicio de cada orden
@command{./pre-inst-env} (el guión @file{pre-inst-env} se encuentra en la
raíz del árbol de compilación de Guix; se genera ejecutando
@command{./bootstrap} seguido de @command{./configure}). A modo de ejemplo
puede ver a continuación cómo construiría el paquete @code{hello} que se
encuentre definido en su directorio de trabajo (esto asume que @command{guix
daemon} se esté ejecutando en su sistema; no es un problema que la versión
sea diferente):

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

@noindent
De manera similar, un ejemplo de una sesión de Guile con los módulos Guix
disponibles:

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

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

@noindent
@cindex REPL
@cindex sesión interactiva
@dots{} and for a REPL (@pxref{Using Guix Interactively}):

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

Si modifica el código del daemon o código auxiliar, o si
@command{guix-daemon} no se está ejecutando todavía en su sistema, puede
ejecutarlo desde el árbol de construción@footnote{La opción @option{-E} a
@command{sudo} asegura que @code{GUILE_LOAD_PATH} contiene la información
correcta para que @command{guix-daemon} y las herramientas que usa puedan
encontrar los módulos Guile que necesitan.}:

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

El guión @command{pre-inst-env} proporciona valor a todas las variables de
entorno necesarias para permitirlo, incluyendo @env{PATH} y
@env{GUILE_LOAD_PATH}.

Fíjese que la orden @command{./pre-inst-env guix pull} @emph{no} actualiza
el árbol de fuentes local; simplemente actualiza el enlace
@file{~/.config/guix/latest} (@pxref{Invocación de guix pull}). Ejecute
@command{git pull} si quiere actualizar su árbol de fuentes local.

A veces, especialmente si ha actualizado recientemente su repositorio, la
ejecución de @command{./pre-inst-env} imprimirá un mensaje similar al
siguiente ejemplo:

@example
;;; nota: archivo fuente /home/user/projects/guix/guix/progress.scm
;;; más reciente que el compilado /home/user/projects/guix/guix/progress.go
@end example

Esto es sólo una nota y se puede ignorar con seguridad.   Puede deshacerse
del mensaje ejecutando @command{make -j4}.   Hasta que lo haga, Guile se
ejecutará ligeramente más lento porque interpretará el código en lugar de
utilizar archivos de objetos Guile preparados (@file{.go}).

Puede ejecutar @command{make} automáticamente mientras trabaja utilizando
@command{watchexec} del paquete @code{watchexec}.  Por ejemplo, para
construir de nuevo cada vez que actualice un archivo de paquete, ejecute
@samp{watchexec -w gnu/packages -- make -j4}.

@node La configuración perfecta
@section La configuración perfecta

La configuración perfecta para hackear en Guix es básicamente la
configuración perfecta para hacerlo en Guile (@pxref{Using Guile in Emacs,,,
guile, Guile Reference Manual}). Primero, necesita más que un editor,
necesita @url{https://www.gnu.org/software/emacs, Emacs}, con su potencia
aumentada gracias al maravilloso @url{https://nongnu.org/geiser,
Geiser}. Para conseguir esta configuración ejecute:

@example
guix install emacs guile emacs-geiser emacs-geiser-guile
@end example

Geiser permite desarrollo incremental e interactivo dentro de Emacs:
compilación y evaluación de código dentro de los buffers, acceso a
documentación en línea (docstrings), completado dependiente del contexto,
@kbd{M-.} para saltar a la definición de un objeto, una consola interactiva
(REPL) para probar su código, y más (@pxref{Introducción,,, geiser, Geiser
User Manual}). Para desarrollar Guix adecuadamente, asegúrese de aumentar la
ruta de carga de Guile (load-path) para que encuentre los archivos fuente de
su copia de trabajo:

@lisp
;; @r{Suponiendo que la copia de trabajo de Guix está en ~/src/guix.}
(with-eval-after-load 'geiser-guile
  (add-to-list 'geiser-guile-load-path "~/src/guix"))
@end lisp

Para realmente editar el código, Emacs tiene un modo para Scheme muy
limpio. Pero además de eso, no debe perderse
@url{http://www.emacswiki.org/emacs/ParEdit, Paredit}. Provee de facilidades
para operar directamente en el árbol sintáctico como elevar una expresión-S
o recubrirla, embeber o expulsar la siguiente expresión-S, etc.

@cindex fragmentos de código
@cindex plantillas
@cindex reducir la verborrea
We also provide templates for common git commit messages and package
definitions in the @file{etc/snippets} directory.  These templates can be
used to expand short trigger strings to interactive text snippets. If you
use @url{https://joaotavora.github.io/yasnippet/, YASnippet}, you may want
to add the @file{etc/snippets/yas} snippets directory to the
@var{yas-snippet-dirs} variable.  If you use
@url{https://github.com/minad/tempel/, Tempel}, you may want to add the
@file{etc/snippets/tempel/*} path to the @var{tempel-path} variable in
Emacs.

@lisp
;; @r{Suponiendo que el checkout de Guix está en ~/src/guix.}
;; @r{Configuración de yasnippet}
(with-eval-after-load 'yasnippet
   (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets/yas"))
;; @r{Tempel configuration}
(con-eval-after-load 'tempel
    ;; Asegúrese de que tempel-path es una lista -- también puede ser una cadena.
    (unless (listp 'tempel-path)
       (setq tempel-path (list tempel-path))
    (add-to-list 'tempel-path "~/src/guix/etc/snippets/tempel/*"))
@end lisp

Los fragmentos de mensajes de la revisión dependen de
@url{https://magit.vc/, Magit} para mostrar los archivos preparados. En la
edición del mensaje de la revisión teclee @code{add} seguido de @kbd{TAB}
(el tabulador) para insertar la plantilla del mensaje de la revisión de
adición de un paquete; teclee @code{update} seguido de @kbd{TAB} para
insertar una plantilla de actualización de un paquete; teclee @code{https}
seguido de @kbd{TAB} para insertar una plantilla para cambiar la URI de la
página de un paquete a HTTPS.

El fragmento principal para @code{scheme-mode} es activado al teclear
@code{package...} seguido de @kbd{TAB}. Este fragmento también inserta el
lanzador @code{origin...} que puede ser expandido de nuevo. El fragmento
@code{origin} puede a su vez insertar otros identificadores de lanzado
terminando en @code{...}, que pueden ser expandidos de nuevo.

@cindex introduce o actualiza el copyright
@cindex @code{M-x guix-copyright}
@cindex @code{M-x copyright-update}
También proporcionamos herramientas para la inserción y actualización
automática del copyright en @file{etc/copyright.el}. Puede proporcionar su
nombre completo, correo electrónico y cargar el archivo.

@lisp
(setq user-full-name "Alicia Díaz")
(setq user-mail-address "alicia@@correo.org")
;; @r{Se asume que la copia trabajo de guix está en ~/src/guix.}
(load-file "~/src/guix/etc/copyright.el")
@end lisp

Para insertar el aviso de copyright en la línea actual invoque @code{M-x
guix-copyright}.

Para actualizar el aviso de copyright debe especificar una expresión regular
de nombres en la variable @code{copyright-names-regexp}.

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

Puede comprobar si su copyright está actualizado evaluando @code{M-x
copyright-update}. Si desea hacerlo de manera automática tras guardar un
archivo añada @code{(add-hook 'after-save-hook 'copyright-update)} en Emacs.

@node Pautas de empaquetamiento
@section Pautas de empaquetamiento

@cindex paquetes, creación
La distribución GNU es reciente y puede no disponer de alguno de sus
paquetes favoritos. Esta sección describe cómo puede ayudar a hacer crecer
la distribución.

Los paquetes de software libre habitualmente se distribuyen en forma de
@dfn{archivadores de código fuente}---típicamente archivos @file{tar.gz} que
contienen todos los archivos fuente. Añadir un paquete a la distribución
significa esencialmente dos cosas: añadir una @dfn{receta} que describe cómo
construir el paquete, la que incluye una lista de otros paquetes necesarios
para la construcción, y añadir @dfn{metadatos del paquete} junto a dicha
receta, como la descripción y la información de licencias.

En Guix toda esta información está contenida en @dfn{definiciones de
paquete}. Las definiciones de paquete proporcionan una vista de alto nivel
del paquete. Son escritas usando la sintaxis del lenguaje de programación
Scheme; de hecho, definimos una variable por cada paquete enlazada a su
definición y exportamos esa variable desde un módulo (@pxref{Módulos de paquetes}). No obstante, un conocimiento profundo de Scheme @emph{no} es un
pre-requisito para la creación de paquetes. Para más información obre las
definiciones de paquetes, @pxref{Definición de paquetes}.

Una vez que una definición de paquete está en su lugar, almacenada en un
archivo del árbol de fuentes de Guix, puede probarse usando la orden
@command{guix build} (@pxref{Invocación de guix build}). Por ejemplo, asumiendo
que el nuevo paquete se llama @code{gnuevo}, puede ejecutar esta orden desde
el árbol de construcción de Guix (@pxref{Ejecución de Guix antes de estar instalado}):

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

El uso de @code{--keep-failed} facilita la depuración de errores de
construcción ya que proporciona acceso al árbol de la construcción
fallida. Otra opción útil de línea de órdenes para la depuración es
@code{--log-file}, para acceder al log de construcción.

Si el paquete resulta desconocido para la orden @command{guix}, puede ser
que el archivo fuente contenga un error de sintaxis, o no tenga una cláusula
@code{define-public} para exportar la variable del paquete. Para encontrar
el problema puede cargar el módulo desde Guile para obtener más información
sobre el error real:

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

Once your package builds correctly, please send us a patch
(@pxref{Envío de parches}).  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{https://@value{SUBSTITUTE-SERVER-1}, our continuous integration
system}.

@cindex servidor de sustituciones
Users can obtain the new package definition simply by running @command{guix
pull} (@pxref{Invocación de guix pull}).  When @code{@value{SUBSTITUTE-SERVER-1}}
is done building the package, installing the package automatically downloads
binaries from there (@pxref{Sustituciones}).  The only place where human
intervention is needed is to review and apply the patch.


@menu
* Libertad del software::    Qué puede entrar en la distribución.
* Nombrado de paquetes::     ¿Qué hay en un nombre?
* Versiones numéricas::     Cuando el nombre no es suficiente.
* Sinopsis y descripciones::  Ayuda para que las usuarias encuentren el 
                                paquete correcto.
* @code{snippets} frente a fases::  ¿Debo usar @code{snippet} o una fase de 
                                      construcción?
* Paquetes Emacs::           Su corrección Elisp.
* Módulos Python::          Un toque de comedia británica.
* Módulos Perl::            Pequeñas perlas.
* Paquetes Java::            La parada del café.
* Crates de Rust::           Sistema de paquetes de Rust.
* Paquetes Elm::             Árboles de código del navegador
* Tipos de letra::           Satisfecho con los tipos de letra.
@end menu

@node Libertad del software
@subsection Libertad del software

@c Adapted from http://www.gnu.org/philosophy/philosophy.html.
@cindex código libre
El sistema operativo GNU se ha desarrollado para que las usuarias puedan
ejercitar su libertad de computación. GNU es @dfn{software libre}, lo que
significa que las usuarias tienen las
@url{https://www.gnu.org/philosophy/free-sw.html,cuatro libertades
esenciales}: para ejecutar el programa, para estudiar y modificar el
programa en la forma de código fuente, para redistribuir copias exactas y
para distribuir versiones modificadas. Los paquetes encontrados en la
distribución GNU contienen únicamente software que proporciona estas cuatro
libertades.

Además, la distribución GNU sigue las
@url{https://www.gnu.org/distros/free-system-distribution-guidelines.html,directrices
de distribución de software libre}. Entre otras cosas, estas directrices
rechazan firmware no-libre, recomendaciones de software no-libre, y tienen
en cuenta formas de tratar con marcas registradas y patentes.

Algunos paquetes originales, que serían de otra manera software libre,
contienen un subconjunto pequeño y opcional que viola estas directrices, por
ejemplo debido a que ese subconjunto sea en sí código no-libre. Cuando esto
sucede, las partes indeseadas son eliminadas con parches o fragmentos de
código en la forma @code{origin} del paquete (@pxref{Definición de paquetes}). De
este modo, @code{guix build --source} devuelve las fuentes ``liberadas'' en
vez de la versión original de las fuentes.


@node Nombrado de paquetes
@subsection Nombrado de paquetes

@cindex nombre de paquete
Un paquete tiene actualmente dos nombre asociados con él. Primero el nombre
de la @emph{Variable Scheme}, seguido de @code{define-public}. Por este
nombre, el paquete se puede conocer por este nombre en el código Scheme, por
ejemplo como entrada a otro paquete. El segundo es la cadena en el campo
@code{nombre} de la definición de paquete. Este nombre es el utilizado por
los comandos de administración de paquetes como @command{guix package} y
@command{guix build}.

Ambos normalmente son iguales y corresponden a la conversión a minúsculas
del nombre de proyecto elegido por sus creadoras, con los guiones bajos
sustituidos por guiones. Por ejemplo, GNUnet está disponible como
@code{gnunet}, y SDL_net como @code{sdl-net}.

Una excepción notable a esta regla es cuando el nombre del proyecto es un
sólo carácter o si existe un proyecto más antiguo mantenido con el mismo
nombre ---sin importar si ha sido empaquetado para Guix. Utilice el sentido
común para hacer que estos nombre no sean ambiguos y tengan significado. Por
ejemplo, el paquete de Guix para la shell llamado ``s'' hacia arriba es
@code{s-shell} y @emph{not} @code{s}. No dude en pedir inspiración a sus
compañeros hackers.

No añadimos prefijos @code{lib} para paquetes de bibliotecas, a menos que
sean parte del nombre oficial del proyecto. Pero vea @ref{Módulos Python} y
@ref{Módulos Perl} para reglas especiales que conciernen a los módulos de
los lenguajes Python y Perl.

Los nombres de paquetes de tipografías se manejan de forma diferente,
@pxref{Tipos de letra}.


@node Versiones numéricas
@subsection Versiones numéricas

@cindex versión de paquete
Normalmente empaquetamos únicamente la última versión de un proyecto dado de
software libre. Pero a veces, por ejemplo para versiones de bibliotecas
incompatibles, se necesitan dos (o más) versiones del mismo paquete. Estas
necesitan nombres diferentes para las variables Scheme. Usamos el nombre
como se define en @ref{Nombrado de paquetes} para la versión más reciente; las
versiones previas usan el mismo nombre, añadiendo un @code{-} y el prefijo
menor del número de versión que permite distinguir las dos versiones.

El nombre dentro de la definición de paquete es el mismo para todas las
versiones de un paquete y no contiene ningún número de versión.

Por ejemplo, las versiones 2.24.20 y 3.9.12 de GTK+ pueden empaquetarse como
sigue:

@lisp
(define-public gtk+
  (package
    (name "gtk+")
    (version "3.9.12")
    ...))
(define-public gtk+-2
  (package
    (name "gtk+")
    (version "2.24.20")
    ...))
@end lisp
Si también deseásemos GTK+3.8.2, se empaquetaría 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 versión, para revisiones de VCS
De manera ocasional, empaquetamos instantáneas del sistema de control de
versiones (VCS) de las desarrolladoras originales en vez de publicaciones
formales. Esto debería permanecer como algo excepcional, ya que son las
desarrolladoras originales quienes deben clarificar cual es la entrega
estable. No obstante, a veces es necesario. Por tanto, ¿qué deberíamos poner
en el campo @code{version}?

Claramente, tenemos que hacer visible el identificador de la revisión en el
VCS en la cadena de versión, pero también debemos asegurarnos que la cadena
de versión incrementa monotónicamente de manera que @command{guix package
--upgrade} pueda determinar qué versión es más moderna. Ya que los
identificadores de revisión, notablemente en Git, no incrementan
monotónicamente, añadimos un número de revisión que se incrementa cada vez
que actualizamos a una nueva instantánea. La versión que resulta debería ser
así:

@example
2.0.11-3.cabba9e
  ^    ^    ^
  |    |    `-- ID de revisión original
  |    |
  |    `--- revisión del paquete Guix
  |
última versión de publicación
@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).  There are
helper functions for doing this for packages using @code{git-fetch} or
@code{hg-fetch} (see below).  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 mi-paquete
  (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
        (revision "1"))          ;Revisión Guix del paquete
    (package
      (version (git-version "0.9" revision commit))
      (source (origin
                (method git-fetch)
                (uri (git-reference
                      (url "git://example.org/mi-paquete.git")
                      (commit commit)))
                (sha256 (base32 "1mbikn@dots{}"))
                (file-name (git-file-name name version))))
      ;; @dots{}
      )))
@end lisp

@deffn {Scheme Procedure} git-version @var{VERSION} @var{REVISION} @var{COMMIT}
Return the version string for packages using @code{git-fetch}.

@lisp
(git-version "0.2.3" "0" "93818c936ee7e2f1ba1b315578bde363a7d43d05")
@result{} "0.2.3-0.93818c9"
@end lisp
@end deffn

@deffn {Scheme Procedure} hg-version @var{VERSION} @var{REVISION} @var{CHANGESET}
Devuelve la cadena de versión de los paquetes utilizando @code{hg-fetch}.
Funciona de la misma manera que @code{git-version}.
@end deffn

@node Sinopsis y descripciones
@subsection Sinopsis y descripciones

@cindex descripción de paquete
@cindex sinopsis de paquete
Como hemos visto previamente, cada paquete en GNU@tie{}Guix incluye una
sinopsis y una descripción (@pxref{Definición de paquetes}). Las sinopsis y
descripciones son importantes: son en lo que @command{guix package --search}
busca, y una pieza crucial de información para ayudar a las usuarias a
determinar si un paquete dado cubre sus necesidades. Consecuentemente, las
empaquetadoras deben prestar atención a qué se incluye en ellas.

Las sinopsis deben empezar con mayúscula y no deben terminar con punto. No
deben empezar con un artículo que habitualmente no aporta nada; por ejemplo,
se prefiere ``Herramienta para chiribizar'' sobre ``Una herramienta que
chiribiza archivos''. La sinopsis debe decir qué es el paquete---por
ejemplo, ``Utilidades básicas GNU (archivos, texto, intérprete de
consola)''---o para qué se usa---por ejemplo, la sinopsis de GNU@tie{}grep
es ``Imprime líneas aceptadas por un patrón''.

Tenga en cuenta que las sinopsis deben tener un claro significado para una
audiencia muy amplia. Por ejemplo, ``Manipula la alineación en el formato
SAM'' puede tener sentido para una investigadora de bioinformática con
experiencia, pero puede ser de poca ayuda o incluso llevar a confusión a una
audiencia no-especializada. Es una buena idea proporcionar una sinopsis que
da una idea del dominio de aplicación del paquete. En ese ejemplo, esto
podría ser algo como ``Manipula la alineación de secuencias de
nucleótidos'', lo que con suerte proporcionará a la usuaria una mejor idea
sobre si esto es lo que está buscando.

Las descripciones deben tener entre cinco y diez líneas. Use frases
completas, y evite usar acrónimos sin introducirlos previamente. Por favor
evite frases comerciales como ``líder mundial'', ``de potencia industrial''
y ``siguiente generación'', y evite superlativos como ``el más
avanzado''---no son útiles para las usuarias que buscan un paquete e incluso
pueden sonar sospechosas. En vez de eso, intente ceñirse a los hechos,
mencionando casos de uso y características.

@cindex marcado Texinfo, en descripciones de paquetes
Descriptions can include Texinfo markup, which is useful to introduce
ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or hyperlinks
(@pxref{Overview,,, texinfo, GNU Texinfo}).  However you should be careful
when using some characters for example @samp{@@} and curly braces which are
the basic special characters in Texinfo (@pxref{Special Characters,,,
texinfo, GNU Texinfo}).  User interfaces such as @command{guix show} take
care of rendering it appropriately.

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 a @command{xgettext} extraerlas como cadenas traducibles, las
sinopsis y descripciones @emph{deben ser cadenas literales}. Esto significa
que no puede usar @code{string-append} o @code{format} para construir estas
cadenas:

@lisp
(package
  ;; @dots{}
  (synopsis "Esto es traducible")
  (description (string-append "Esto " "*no*" " es traducible.")))
@end lisp

La traducción requiere mucho trabajo, por lo que, como empaquetadora, le
rogamos que ponga incluso más atención a sus sinopsis y descripciones ya que
cada cambio puede suponer trabajo adicional para las traductoras. Para
ayudarlas, es posible hacer recomendaciones o instrucciones insertando
comentarios especiales como este (@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 @code{snippets} frente a fases
@subsection @code{snippets} frente a fases

@cindex snippets, cuándo usar
La frontera entre el uso de un fragmento de código para la modificación de
un origen (@code{snippet}) frente a una fase de construcción puede ser
ténue. Los fragmentos de código para el origen se usan habitualmente para
eliminar archivos no deseados, como bibliotecas incluidas, fuentes no
libres, o simplemente para aplicar sustituciones simples. Las fuentes que
derivan de un origen deben producir unas fuentes capaces de compilar en
cualquier sistema que permita el paquete original (es decir, actuar como la
fuente correspondiente). En particular, los @code{snippet} del campo
@code{origin} no deben incluir elementos del almacén en las fuentes; esos
parches deben llevarse a cabo en las fases de construcción. Véase el
registro @code{origin} para obtener más información (@pxref{Referencia de origin}).

@node Paquetes Emacs
@subsection Paquetes Emacs

@cindex emacs, packaging
@cindex elisp, packaging
Los paquetes Emacs deberían usar preferentemente el sistema de construcción
de Emacs (@pxref{emacs-build-system}), por uniformidad y por los beneficios
que proporcionan sus fases de construcción, tales como la autogeneración del
fichero de autocargas y la compilación de bytes de las fuentes.   Debido a
que no hay una forma estandarizada de ejecutar un conjunto de pruebas para
los paquetes Emacs, las pruebas están deshabilitadas por defecto.   Cuando
un conjunto de pruebas está disponible, debe ser habilitado estableciendo el
argumento @code{#:tests?} a @code{#true}.   Por defecto, el comando para
ejecutar la prueba es @command{make check}, pero se puede especificar
cualquier comando mediante el argumento @code{#:test-command}.   El
argumento @code{#:test-command} espera una lista que contenga un comando y
sus argumentos, para ser invocado durante la fase @code{check}.

Las dependencias de Elisp de los paquetes de Emacs se proporcionan
normalmente como @code{propagated-inputs} cuando se requieren en tiempo de
ejecución.   En cuanto a otros paquetes, las dependencias de construcción o
de prueba deben especificarse como @code{native-inputs}.

Los paquetes de Emacs a veces dependen de directorios de recursos que deben
instalarse junto con los archivos de Elisp.  El argumento @code{#:include}
puede utilizarse para este fin, especificando una lista de expresiones
regulares que deben coincidir.  La mejor práctica cuando se utiliza el
argumento @code{#:include} es ampliar en lugar de anular su valor por
defecto (accesible a través de la variable @code{%default-include}).  Como
ejemplo, un paquete de extensión de yasnippet suele incluir un directorio
@file{snippets}, que podría copiarse en el directorio de instalación
utilizando:

@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
Actualmente empaquetamos Python 2 y Python 3, bajo los nombres de variable
Scheme @code{python-2} y @code{python} como se explica en @ref{Versiones numéricas}. Para evitar confusiones y conflictos de nombres con otros
lenguajes de programación, parece deseable que el nombre de paquete para un
módulo Python contenga la palabra @code{python}.

Algunos módulos son compatibles únicamente con una versión de Python, otros
con ambas. Si el paquete Foo se compila únicamente con Python 3, lo llamamos
@code{python-foo}. Si se compila con Python 2, lo llamamos
@code{python2-foo}. Los paquetes deben añadirse cuando sean necesarios; no
añadimos la variante de Python 2 del paquete a menos que vayamos a usarla.

Si un proyecto ya contiene la palabra @code{python}, la eliminamos; por
ejemplo, el módulo python-dateutil se empaqueta con los nombres
@code{python-dateutil} y @code{python2-dateutil}. Si el nombre del proyecto
empieza con @code{py} (por ejemplo @code{pytz}), este se mantiene y el
prefijo es el especificado anteriormente..

@quotation Nota
Currently there are two different build systems for Python packages in Guix:
@var{python-build-system} and @var{pyproject-build-system}.  For the longest
time, Python packages were built from an informally specified
@file{setup.py} file.  That worked amazingly well, considering Python's
success, but was difficult to build tooling around.  As a result, a host of
alternative build systems emerged and the community eventually settled on a
@url{https://peps.python.org/pep-0517/, formal standard} for specifying
build requirements.  @var{pyproject-build-system} is Guix's implementation
of this standard.  It is considered ``experimental'' in that it does not yet
support all the various PEP-517 @emph{build backends}, but you are
encouraged to try it for new Python packages and report any problems.  It
will eventually be deprecated and merged into @var{python-build-system}.
@end quotation

@subsubsection Especificación de dependencias
@cindex entradas, para paquetes Python

Dependency information for Python packages is usually available in the
package source tree, with varying degrees of accuracy: in the
@file{pyproject.toml} file, the @file{setup.py} file, in
@file{requirements.txt}, or in @file{tox.ini} (the latter mostly for test
dependencies).

Su misión, cuando escriba una receta para un paquete Python, es asociar
estas dependencias con el tipo apropiado de ``entrada'' (@pxref{Referencia de package, inputs}). Aunque el importador de @code{pypi} normalmente hace un
buen trabajo (@pxref{Invocación de guix import}), puede querer comprobar la
siguiente lista para determinar qué dependencia va dónde.

@itemize

@item
We currently package Python with @code{setuptools} and @code{pip} installed
per default.  This is about to change, and users are encouraged to use
@code{python-toolchain} if they want a build environment for Python.

@command{guix lint} will warn if @code{setuptools} or @code{pip} are added
as native-inputs because they are generally not necessary.

@item
Las dependencias Python requeridas en tiempo de ejecución van en
@code{propagated-inputs}. Típicamente están definidas con la palabra clave
@code{install_requires} en @file{setup.py}, o en el archivo
@file{requirements.txt}.

@item
Python packages required only at build time---e.g., those listed under
@code{build-system.requires} in @file{pyproject.toml} or with the
@code{setup_requires} keyword in @file{setup.py}---or dependencies only for
testing---e.g., those in @code{tests_require} or @file{tox.ini}---go into
@code{native-inputs}.  The rationale is that (1) they do not need to be
propagated because they are not needed at run time, and (2) in a
cross-compilation context, it's the ``native'' input that we'd want.

Ejemplos son las bibliotecas de pruebas @code{pytest}, @code{mock} y
@code{nose}. Por supuesto, si alguno de estos paquetes también se necesita
en tiempo de ejecución, necesita ir en @code{propagated-inputs}.

@item
Todo lo que no caiga en las categorías anteriores va a @code{inputs}, por
ejemplo programas o bibliotecas C requeridas para construir los paquetes
Python que contienen extensiones C.

@item
Si un paquete Python tiene dependencias opcionales (@code{extras_require}),
queda en su mano decidir si las añade o no, en base a la relación
utilidad/sobrecarga (@pxref{Envío de parches, @command{guix size}}).

@end itemize


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

@cindex perl
Los programas ejecutables Perl se nombran como cualquier otro paquete,
mediante el uso del nombre oficial en minúsculas. Para paquetes Perl que
contienen una única clase, usamos el nombre en minúsculas de la clase,
substituyendo todas las ocurrencias de @code{::} por guiones y agregando el
prefijo @code{perl-}. Por tanto la clase @code{XML::Parser} se convierte en
@code{perl-xml-parser}. Los módulos que contienen varias clases mantienen su
nombre oficial en minúsculas y también se agrega @code{perl-} al
inicio. Dichos módulos tienden a tener la palabra @code{perl} en alguna
parte de su nombre, la cual se elimina en favor del prefijo. Por ejemplo,
@code{libwww-perl} se convierte en @code{perl-libwww}.


@node Paquetes Java
@subsection Paquetes Java

@cindex java
Los programas Java ejecutables se nombran como cualquier otro paquete,
mediante el uso del nombre oficial en minúsculas.

Para evitar confusión y colisiones de nombres con otros lenguajes de
programación, es deseable que el nombre del paquete para un paquete Java
contenga el prefijo @code{java-}. Si el proyecto ya tiene la palabra
@code{java}, eliminamos esta; por ejemplo, el paquete @code{ngsjaga} se
empaqueta bajo el nombre @code{java-ngs}.

Para los paquetes Java que contienen una clase única o una jerarquía
pequeña, usamos el nombre de clase en minúsculas, substituyendo todas las
ocurrencias de @code{.} por guiones y agregando el prefijo @code{java-}. Por
tanto la clase @code{apache.commons.cli} se convierte en el paquete
@code{java-apache-commons-cli}.


@node Crates de Rust
@subsection Crates de Rust

@cindex rust
Los programas Rust ejecutables se nombran como cualquier otro paquete,
mediante el uso del nombre oficial en minúsculas.

Para evitar colisiones en el espacio de nombres añadimos @code{rust-} como
prefijo al resto de paquetes de Rust. El nombre debe cambiarse a letras
minúsculas cuando sea apropiado y los guiones deben mantenerse.

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}.

Debido a la dificultad a la hora de reusar paquetes de rust como entradas
pre-compiladas de otros paquetes, el sistema de construcción de Cargo
(@pxref{Sistemas de construcción, @code{cargo-build-system}}) presenta las palabras
clave @code{#:cargo-inputs} y @code{cargo-development-inputs} como
parámetros del sistema de construcción. Puede servir de ayuda pensar en
estos parámetros de manera similar a @code{propagated-inputs} y
@code{native-inputs}. Las dependencias de rust de @code{dependencies} y
@code{build-dependencies} deben proporcionarse a través de
@code{#:cargo-inputs}, y @code{dev-dependencies} deben proporcionarse a
través de @code{#:cargo-development-inputs}. Si un paquete de Rust se enlaza
con otras bibliotecas deben proporcionarse como habitualmente en
@code{inputs} y otros campos relacionados.

Se debe tener cuidado a la hora de asegurar que se usan las versiones
correctas de las dependencias; para ello intentamos no evitar la ejecución
de pruebas o la construcción completa con @code{#:skip-build?} cuando sea
posible. Por supuesto, no siempre es posible, ya que el paquete puede
desarrollarse para un sistema operativo distinto, depender de
características del compilador de Rust que se construye a diario (Nightly),
o la batería de pruebas puede haberse atrofiado desde su lanzamiento.


@node Paquetes Elm
@subsection Paquetes Elm

@cindex Elm
Elm applications can be named like other software: their names need not
mention Elm.

Packages in the Elm sense (see @code{elm-build-system} under @ref{Sistemas de construcción}) are required use names of the format
@var{author}@code{/}@var{project}, where both the @var{author} and the
@var{project} may contain hyphens internally, and the @var{author} sometimes
contains uppercase letters.

To form the Guix package name from the upstream name, we follow a convention
similar to Python packages (@pxref{Módulos Python}), adding an @code{elm-}
prefix unless the name would already begin with @code{elm-}.

In many cases we can reconstruct an Elm package's upstream name
heuristically, but, since conversion to a Guix-style name involves a loss of
information, this is not always possible.  Care should be taken to add the
@code{'upstream-name} property when necessary so that @samp{guix import elm}
will work correctly (@pxref{Invocación de guix import}). The most notable
scenarios when explicitly specifying the upstream name is necessary are:

@enumerate
@item
When the @var{author} is @code{elm} and the @var{project} contains one or
more hyphens, as with @code{elm/virtual-dom}; and

@item
When the @var{author} contains hyphens or uppercase letters, as with
@code{Elm-Canvas/raster-shapes}---unless the @var{author} is
@code{elm-explorations}, which is handled as a special case, so packages
like @code{elm-explorations/markdown} do @emph{not} need to use the
@code{'upstream-name} property.
@end enumerate

The module @code{(guix build-system elm)} provides the following utilities
for working with names and related conventions:

@deffn {Scheme procedure} elm-package-origin @var{elm-name} @var{version} @
  @var{hash} Returns a Git origin using the repository naming and tagging
regime required for a published Elm package with the upstream name
@var{elm-name} at version @var{version} with sha256 checksum @var{hash}.

Por ejemplo:
@lisp
(package
  (name "elm-html")
  (version "1.0.0")
  (source
   (elm-package-origin
    "elm/html"
    version
    (base32 "15k1679ja57vvlpinpv06znmrxy09lbhzfkzdc89i01qa8c4gb4a")))
  ...)
@end lisp
@end deffn

@deffn {Scheme procedure} elm->package-name @var{elm-name}
Returns the Guix-style package name for an Elm package with upstream name
@var{elm-name}.

Note that there is more than one possible @var{elm-name} for which
@code{elm->package-name} will produce a given result.
@end deffn

@deffn {Scheme procedure} guix-package->elm-name @var{package}
Given an Elm @var{package}, returns the possibly-inferred upstream name, or
@code{#f} the upstream name is not specified via the @code{'upstream-name}
property and can not be inferred by @code{infer-elm-package-name}.
@end deffn

@deffn {Scheme procedure} infer-elm-package-name @var{guix-name}
Given the @var{guix-name} of an Elm package, returns the inferred upstream
name, or @code{#f} if the upstream name can't be inferred.  If the result is
not @code{#f}, supplying it to @code{elm->package-name} would produce
@var{guix-name}.
@end deffn

@node Tipos de letra
@subsection Tipos de letra

@cindex tipografías
Para tipografías que no se instalan generalmente por una usuaria para
propósitos tipográficos, o que se distribuyen como parte de un paquete de
software más grande, seguimos las reglas generales de empaquetamiento de
software; por ejemplo, esto aplica a las tipografías distribuidas como parte
del sistema X.Org o las tipografías que son parte de TeX Live.

Para facilitar a las usuarias la búsqueda de tipografías, los nombres para
otros paquetes que contienen únicamente tipografías se construyen como
sigue, independientemente del nombre de paquete oficial.

El nombre de un paquete que contiene únicamente una familia tipográfica
comienza con @code{font-}; seguido por el nombre de la tipografía y un guión
si la tipografía es conocida, y el nombre de la familia tipográfica, donde
los espacios se sustituyen por guiones (y como es habitual, todas las letras
mayúsculas se transforman a minúsculas). Por ejemplo, la familia de
tipografías Gentium de SIL se empaqueta bajo el nombre de
@code{font-sil-gentium}.

Para un paquete que contenga varias familias tipográficas, el nombre de la
colección se usa en vez del nombre de la familia tipográfica. Por ejemplo,
las tipografías Liberation consisten en tres familias: Liberation Sans,
Liberation Serif y Liberation Mono. Estas se podrían empaquetar por separado
bajo los nombres @code{font-liberation-sans}, etcétera; pero como se
distribuyen de forma conjunta bajo un nombre común, preferimos empaquetarlas
conjuntamente como @code{font-liberation}.

En el caso de que varios formatos de la misma familia o colección
tipográfica se empaqueten de forma separada, una forma corta del formato,
precedida por un guión, se añade al nombre del paquete. Usamos @code{-ttf}
para tipografías TrueType, @code{-otf} para tipografías OpenType y
@code{-type1} para tipografías Tipo 1 PostScript.


@node Estilo de codificación
@section Estilo de codificación

En general nuestro código sigue los Estándares de codificación GNU
(@pxref{Top,,, standards, GNU Coding Standards}). No obstante, no dicen
mucho de Scheme, así que aquí están algunas reglas adicionales.

@menu
* Paradigma de programación::  Cómo componer sus elementos.
* Módulos::                 ¿Dónde almacenar su código?
* Tipos de datos y reconocimiento de patrones::  Implementación de 
                                                   estructuras de datos.
* Formato del código::      Convenciones de escritura.
@end menu

@node Paradigma de programación
@subsection Paradigma de programación

El código scheme en Guix está escrito en un estilo puramente funcional. Una
excepción es el código que incluye entrada/salida, y procedimientos que
implementan conceptos de bajo nivel, como el procedimiento @code{memoize}.

@node Módulos
@subsection Módulos

Los módulos Guile que están destinados a ser usados en el lado del
constructor deben encontrarse en el espacio de nombres @code{(guix build
@dots{})}. No deben hacer referencia a otros módulos Guix o GNU. No
obstante, no hay problema en usar un módulo del lado del constructor en un
módulo ``del lado del cliente''.

Los módulos que tratan con el sistema GNU más amplio deben estar en el
espacio de nombres @code{(gnu @dots{})} en vez de en @code{(guix @dots{})}.

@node Tipos de datos y reconocimiento de patrones
@subsection Tipos de datos y reconocimiento de patrones

La tendencia en el Lisp clásico es usar listas para representar todo, y
recorrerlas ``a mano'' usando @code{car}, @code{cdr}, @code{cadr} y
compañía. Hay varios problemas con este estilo, notablemente el hecho de que
es difícil de leer, propenso a errores y una carga para informes adecuados
de errores de tipado.

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 Formato del código
@subsection Formato del código

@cindex dar formato al código
@cindex estilo de codificación
Cuando escribimos código Scheme, seguimos la sabiduría común entre las
programadoras Scheme. En general, seguimos las
@url{https://mumble.net/~campbell/scheme/style.txt, Reglas de estilo Lisp de
Riastradh}. Este documento resulta que también describe las convenciones más
usadas en el código Guile. Está lleno de ideas y bien escrito, así que
recomendamos encarecidamente su lectura.

Algunas formas especiales introducidas en Guix, como el macro
@code{substitute*} tienen reglas de indentación especiales. Estas están
definidas en el archivo @file{.dir-locals.el}, el cual Emacs usa
automáticamente. Fíjese que además Emacs-Guix proporciona el modo
@code{guix-devel-mode} que indenta y resalta adecuadamente el código de Guix
(@pxref{Desarrollo,,, emacs-guix, The Emacs-Guix Reference Manual}).

@cindex indentación, de código
@cindex formato, de código
Si no usa Emacs, por favor asegúrese de que su editor conoce esas
reglas. Para indentar automáticamente una definición de paquete también
puede ejecutar:

@example
./pre-inst-env guix style @var{package}
@end example

@noindent
@xref{Invoking guix style}, for more information.

@cindex Vim, edición de código Scheme
Si está editando código con Vim, le recomendamos ejecutar @code{:set
autoindent} para que el código se indente automáticamente mientras
escribe. Adicionalmente,
@uref{https://www.vim.org/scripts/script.php?script_id=3998,
@code{paredit.vim}} puede ayudar a manejar todos estos paréntesis.

Requerimos que todos los procedimientos del nivel superior tengan una cadena
de documentación. Este requisito puede relajarse para procedimientos simples
privados en el espacio de nombres @code{(guix build @dots{})} no obstante.

Los procedimientos no deben tener más de cuatro parámetros posicionales. Use
parámetros con palabras clave para procedimientos que toman más de cuatro
parámetros.


@node Envío de parches
@section Envío de parches

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 (@pxref{Submitting patches to a project,,, git, Git User Manual}).  Contributors are encouraged
to take a moment to set some Git repository options (@pxref{Configuring Git}) first, which can improve the readability of patches.  Seasoned Guix
developers may also want to look at the section on commit access
(@pxref{Acceso al repositorio}).

This mailing list is backed by a Debbugs instance, which allows us to keep
track of submissions (@pxref{Seguimiento de errores y parches}).  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{ISSUE_NUMBER}@@debbugs.gnu.org}, where @var{ISSUE_NUMBER} is the
tracking number (@pxref{Envío de una serie de parches}).

Le rogamos que escriba los mensajes de revisiones en formato ChangeLog
(@pxref{Change Logs,,, standards, GNU Coding Standards}); puede comprobar la
historia de revisiones en busca de ejemplos.

Antes de enviar un parche que añade o modifica una definición de un paquete,
por favor recorra esta lista de comprobaciones:

@enumerate
@item
Si las autoras del paquete software proporcionan una firma criptográfica
para el archivo de la versión, haga un esfuerzo para verificar la
autenticidad del archivo. Para un archivo de firma GPG separado esto puede
hacerse con la orden @code{gpg --verify}.

@item
Dedique algún tiempo a proporcionar una sinopsis y descripción adecuadas
para el paquete. @xref{Sinopsis y descripciones}, para algunas directrices.

@item
Ejecute @code{guix lint @var{paquete}}, donde @var{paquete} es el nombre del
paquete nuevo o modificado, y corrija cualquier error del que informe
(@pxref{Invocación de guix lint}).

@item
Run @code{guix style @var{package}} to format the new package definition
according to the project's conventions (@pxref{Invoking guix style}).

@item
Asegúrese de que el paquete compile en su plataforma, usando @code{guix
build @var{package}}.

@item
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 @code{qemu-binfmt-service-type} to emulate them.  In
order to enable it, add the @code{virtualization} service module and the
following service to the list of services in your @code{operating-system}
configuration:

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

Una vez hecho esto, reconfigure su sistema.

You can then build packages for different platforms by specifying the
@code{--system} option.  For example, to build the "hello" package for the
armhf or aarch64 architectures, you would run the following commands,
respectively:
@example
guix build --system=armhf-linux --rounds=2 hello
guix build --system=aarch64-linux --rounds=2 hello
@end example

@item
@cindex empaquetamientos
Asegúrese de que el paquete no usa copias empaquetadas de software ya
disponible como paquetes separados.

A veces, paquetes incluyen copias embebidas del código fuente de sus
dependencias para conveniencia de las usuarias. No obstante, como
distribución, queremos asegurar que dichos paquetes efectivamente usan la
copia que ya tenemos en la distribución si hay ya una. Esto mejora el uso de
recursos (la dependencia es construida y almacenada una sola vez), y permite
a la distribución hacer cambios transversales como aplicar actualizaciones
de seguridad para un software dado en un único lugar y que afecte a todo el
sistema---algo que esas copias embebidas impiden.

@item
Take a look at the profile reported by @command{guix size} (@pxref{Invocación de 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{Paquetes con múltiples salidas}), 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
For important changes, check that dependent packages (if applicable) are not
affected by the change; @code{guix refresh --list-dependent @var{package}}
will help you do that (@pxref{Invocación de guix refresh}).

@c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>.
@cindex estrategia de ramas
@cindex estrategia de planificación de reconstrucciones
En base al número de paquetes dependientes y, por tanto, del tamaño de la
reconstrucción inducida, los revisiones van a ramas separadas, según estas
líneas:

@table @asis
@item 300 paquetes dependientes o menos
rama @code{master} (cambios no disruptivos).

@item entre 300 y 1.800 paquetes dependientes
@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}).  This branch is not expected to be buildable or
usable until late in its development process.

@item más de 1.800 paquetes dependientes
@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.  This branch is not expected to be buildable or usable until
late in its development process.
@end table

All these branches are @uref{https://@value{SUBSTITUTE-SERVER-1}, 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, del proceso de construcción
@cindex construcciones reproducibles, comprobar
Compruebe si el proceso de construcción de un paquete es determinista. Esto
significa típicamente comprobar si una construcción independiente del
paquete ofrece exactamente el mismo resultado que usted obtuvo, bit a bit.

Una forma simple de hacerlo es construyendo el mismo paquete varias veces
seguidas en su máquina (@pxref{Invocación de guix build}):

@example
guix build --rounds=2 mi-paquete
@end example

Esto es suficiente una clase común de problemas de no-determinismo, como las
marcas de tiempo o salida generada aleatoriamente en el resultado de la
construcción.

Another option is to use @command{guix challenge} (@pxref{Invocación de guix challenge}).  You may run it once the package has been committed and built
by @code{@value{SUBSTITUTE-SERVER-1}} to check whether it obtains the same
result as you did.  Better yet: Find another machine that can build it and
run @command{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 @code{uname} or @file{/proc}
files.

@item
Cuando escriba documentación, por favor use construcciones neutrales de
género para referirse a la gente@footnote{NdT: En esta traducción se ha
optado por usar el femenino para referirse a @emph{personas}, ya que es el
género gramatical de dicha palabra. Aunque las construcciones impersonales
pueden adoptarse en la mayoría de casos, también pueden llegar a ser muy
artificiales en otros usos del castellano; en ocasiones son directamente
imposibles. Algunas construcciones que proponen la neutralidad de género
dificultan la lectura automática (-x), o bien dificultan la corrección
automática (-e), o bien aumentan significativamente la redundancia y reducen
del mismo modo la velocidad en la lectura (-as/os, -as y -os). No obstante,
la adopción del genero neutro heredado del latín, el que en castellano se ha
unido con el masculino, como construcción neutral de género se considera
inaceptable, ya que sería equivalente al ``it'' en inglés, nada más lejos de
la intención de las autoras originales del texto.}, como
@uref{https://en.wikipedia.org/wiki/Singular_they, singular ``they''@comma{}
``their''@comma{} ``them''} y demás.

@item
Compruebe que su parche contiene únicamente un conjunto relacionado de
cambios. Agrupando cambios sin relación dificulta y ralentiza la revisión.

Ejemplos de cambios sin relación incluyen la adición de varios paquetes, o
una actualización de un paquete junto a correcciones a ese paquete.

@item
Please follow our code formatting rules, possibly running @command{guix
style} script to do that automatically for you (@pxref{Formato del código}).

@item
Cuando sea posible, use espejos en la URL de las fuentes (@pxref{Invocación de guix download}). Use URL fiables, no generadas. Por ejemplo, los archivos de
GitHub no son necesariamente idénticos de una generación a la siguiente, así
que en este caso es normalmente mejor clonar el repositorio. No use el campo
@command{name} en la URL: no es muy útil y si el nombre cambia, la URL
probablemente estará mal.

@item
Comprueba si Guix se puede construir correctamente (@pxref{Construcción desde Git}) y trata los avisos, especialmente aquellos acerca del uso de símbolos
sin definición.

@item
Asegúrese de que sus cambios no rompen Guix y simule @code{guix pull} con:
@example
guix pull --url=/ruta/a/su/copia --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{Envío de una serie de parches}).  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
@email{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
@email{@var{ISSUE_NUMBER}-done@@debbugs.gnu.org}.

@node Configuring Git
@subsection Configuring Git
@cindex git configuration
@cindex @code{git format-patch}
@cindex @code{git send-email}

If you have not done so already, you may wish to set a name and email that
will be associated with your commits (@pxref{telling git your name, ,
Telling Git your name, git, Git User Manual}).  If you wish to use a
different name or email just for commits in this repository, you can use
@command{git config --local}, or edit @file{.git/config} in the repository
instead of @file{~/.gitconfig}.

We provide some default settings in @file{etc/git/gitconfig} which modify
how patches are generated, making them easier to read and apply.  These
settings can be applied by manually copying them to @file{.git/config} in
your checkout, or by telling Git to include the whole file:

@example
git config --local include.path ../etc/git/gitconfig
@end example

From then on, any changes to @file{etc/git/gitconfig} would automatically
take effect.

Since the first patch in a series must be sent separately (@pxref{Envío de una serie de parches}), it can also be helpful to tell @command{git format-patch} to
handle the e-mail threading instead of @command{git send-email}:

@example
git config --local format.thread shallow
git config --local sendemail.thread no
@end example

@node Envío de una serie de parches
@subsection Envío de una serie de parches
@cindex series de parches
@cindex @code{git send-email}
@cindex @code{git format-patch}

@unnumberedsubsubsec Single Patches
@anchor{Single Patches}
The @command{git send-email} command is the best way to send both single
patches and patch series (@pxref{Multiple Patches}) to the Guix mailing
list.  Sending patches as email attachments may make them difficult to
review in some mail clients, and @command{git diff} does not store commit
metadata.

@quotation Nota
The @command{git send-email} command is provided by the @code{send-email}
output of the @code{git} package, i.e. @code{git:send-email}.
@end quotation

The following command will create a patch email from the latest commit, open
it in your @var{EDITOR} or @var{VISUAL} for editing, and send it to the Guix
mailing list to be reviewed and merged:

@example
$ git send-email -1 -a --base=auto --to=guix-patches@@gnu.org
@end example

@quotation Tip
To add a prefix to the subject of your patch, you may use the
@option{--subject-prefix} option.  The Guix project uses this to specify
that the patch is intended for a branch or repository other than the
@code{master} branch of @url{https://git.savannah.gnu.org/cgit/guix.git}.

@example
git send-email -1 -a --base=auto \
    --subject-prefix='PATCH core-updates' \
    --to=guix-patches@@gnu.org
@end example
@end quotation

The patch email contains a three-dash separator line after the commit
message.  You may ``annotate'' the patch with explanatory text by adding it
under this line.  If you do not wish to annotate the email, you may drop the
@option{-a} flag (which is short for @option{--annotate}).

The @option{--base=auto} flag automatically adds a note at the bottom of the
patch of the commit it was based on, making it easier for maintainers to
rebase and merge your patch.

If you need to send a revised patch, don't resend it like this or send a
``fix'' patch to be applied on top of the last one; instead, use
@command{git commit -a} or @url{https://git-rebase.io, @command{git rebase}}
to modify the commit, and use the
@email{@var{ISSUE_NUMBER}@@debbugs.gnu.org} address and the @option{-v} flag
with @command{git send-email}.

@example
$ git commit -a
$ git send-email -1 -a --base=auto -v @var{REVISION} \
      --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org
@end example

You can find out @var{ISSUE_NUMBER} either by searching on the mumi
interface at @url{issues.guix.gnu.org} for the name of your patch or reading
the acknowledgement email sent automatically by Debbugs in reply to incoming
bugs and patches, which contains the bug number.

@unnumberedsubsubsec Notifying Teams
@anchor{Notifying Teams}
@cindex teams
The @file{etc/teams.scm} script may be used to notify all those who may be
interested in your patch of its existence (@pxref{Teams}).  Use
@command{etc/teams.scm list-teams} to display all the teams, decide which
team(s) your patch relates to, and use @command{etc/teams.scm cc} to output
various @command{git send-email} flags which will notify the appropriate
team members, or use @command{etc/teams.scm cc-members} to detect the
appropriate teams automatically.

@unnumberedsubsubsec Multiple Patches
@anchor{Multiple Patches}
@cindex cover letter
While @command{git send-email} alone will suffice for a single patch, an
unfortunate flaw in Debbugs means you need to be more careful when sending
multiple patches: if you send them all to the @email{guix-patches@@gnu.org}
address, a new issue will be created for each patch!

When sending a series of patches, it's best to send a Git ``cover letter''
first, to give reviewers an overview of the patch series.  We can create a
directory called @file{outgoing} containing both our patch series and a
cover letter called @file{0000-cover-letter.patch} with @command{git
format-patch}.

@example
$ git format-patch -@var{NUMBER_COMMITS} -o outgoing \
      --cover-letter --base=auto
@end example

We can now send @emph{just} the cover letter to the
@email{guix-patches@@gnu.org} address, which will create an issue that we
can send the rest of the patches to.

@example
$ git send-email outgoing/0000-cover-letter.patch -a \
      --to=guix-patches@@debbugs.gnu.org \
      $(etc/teams.scm cc-members ...)
$ rm outgoing/0000-cover-letter.patch # we don't want to resend it!
@end example

Ensure you edit the email to add an appropriate subject line and blurb
before sending it.  Note the automatically generated shortlog and diffstat
below the blurb.

Once the Debbugs mailer has replied to your cover letter email, you can send
the actual patches to the newly-created issue address.

@example
$ git send-email outgoing/*.patch \
      --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org \
      $(etc/teams.scm cc-members ...)
$ rm -rf outgoing # we don't need these anymore
@end example

Thankfully, this @command{git format-patch} dance is not necessary to send
an amended patch series, since an issue already exists for the patchset.

@example
$ git send-email -@var{NUMBER_COMMITS} \
      -v@var{REVISION} --base=auto \
      --to @var{ISSUE_NUMBER}@@debbugs.gnu.org
@end example

If need be, you may use @option{--cover-letter -a} to send another cover
letter, e.g. for explaining what's changed since the last revision, and
these changes are necessary.

@node Teams
@subsection Teams
@cindex teams

There are several teams mentoring different parts of the Guix source code.
To list all those teams, you can run from a Guix checkout:

@example
$ ./etc/teams.scm list-teams
id: mentors
name: Mentors
description: A group of mentors who chaperone contributions by newcomers.
members:
+ Christopher Baines <mail@@cbaines.net>
+ Ricardo Wurmus <rekado@@elephly.net>
+ Mathieu Othacehe <othacehe@@gnu.org>
+ jgart <jgart@@dismail.de>
+ Ludovic Courtès <ludo@@gnu.org>
@dots{}
@end example

You can run the following command to have the @code{Mentors} team put in CC
of a patch series:

@example
$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch
@end example

The appropriate team or teams can also be inferred from the modified files.
For instance, if you want to send the two latest commits of the current Git
repository to review, you can run:

@example
$ guix shell -D guix
[env]$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc-members HEAD~2 HEAD) *.patch
@end example

@node Seguimiento de errores y parches
@section Seguimiento de errores y parches

This section describes how the Guix project tracks its bug reports and patch
submissions.

@menu
* The Issue Tracker::        The official bug and patch tracker.
* Debbugs User Interfaces::  Ways to interact with Debbugs.
* Debbugs Usertags::         Tag reports with custom labels.
@end menu

@node The Issue Tracker
@subsection The Issue Tracker

@cindex informes de errores, seguimiento
@cindex envíos de parches, seguimiento
@cindex seguimiento de incidencias
@cindex Debbugs, sistema de seguimiento de incidencias
El seguimiento de los informes de errores y los envíos de parches se realiza
con una instancia de Debbugs en @uref{https://bugs.gnu.org}. Los informes de
errores se abren para el ``paquete'' @code{guix} (en la jerga de Debbugs),
enviando un correo a @email{bug-guix@@gnu.org}, mientras que para los envíos
de parches se usa el paquete @code{guix-patches} enviando un correo a
@email{guix-patches@@gnu.org} (@pxref{Envío de parches}).

@node Debbugs User Interfaces
@subsection Debbugs User Interfaces

Hay disponible una interfaz web (¡en realidad @emph{dos} interfaces web!)
para la navegación por las incidencias:

@itemize
@item
@url{https://issues.guix.gnu.org} proporciona una agradable interfaz
@footnote{La interfaz web en @url{https://issues.guix.gnu.org} implementada
con Mumi, un interesante software escrito en Guile, ¡y en el que puede
ayudar! Véase @url{https://git.elephly.net/gitweb.cgi?p=software/mumi.git}.}
paranavegar por los informes de errores y parches, y para participar en las
discusiones;
@item
@url{https://bugs.gnu.org/guix} muestra informes de errores;
@item
@url{https://bugs.gnu.org/guix-patches} muestra parches enviados.
@end itemize

Para ver los hilos relacionados con la incidencia número @var{n}, visite
@indicateurl{https://issues.guix.gnu.org/@var{n}} o
@indicateurl{https://bugs.gnu.org/@var{n}}.

Si usa Emacs, puede encontrar más conveniente la interacción con las
incidencias mediante @file{debbugs.el}, que puede instalar con:

@example
guix install emacs-debbugs
@end example

Por ejemplo, para enumerar todos las incidencias abiertas en
@code{guix-patches} pulse:

@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}, para más información sobre
esta útil herramienta.

@node Debbugs Usertags
@subsection Debbugs Usertags

@cindex usertags, for debbugs
@cindex Debbugs usertags
Debbugs provides a feature called @dfn{usertags} that allows any user to tag
any bug with an arbitrary label.  Bugs can be searched by usertag, so this
is a handy way to organize bugs@footnote{The list of usertags is public
information, and anyone can modify any user's list of usertags, so keep that
in mind if you choose to use this feature.}.

For example, to view all the bug reports (or patches, in the case of
@code{guix-patches}) tagged with the usertag @code{powerpc64le-linux} for
the user @code{guix}, open a URL like the following in a web browser:
@url{https://debbugs.gnu.org/cgi-bin/pkgreport.cgi?tag=powerpc64le-linux;users=guix}.

For more information on how to use usertags, please refer to the
documentation for Debbugs or the documentation for whatever tool you use to
interact with Debbugs.

In Guix, we are experimenting with usertags to keep track of
architecture-specific issues.  To facilitate collaboration, all our usertags
are associated with the single user @code{guix}.  The following usertags
currently exist for that user:

@table @code

@item powerpc64le-linux
The purpose of this usertag is to make it easy to find the issues that
matter most for the @code{powerpc64le-linux} system type.  Please assign
this usertag to bugs or patches that affect @code{powerpc64le-linux} but not
other system types.  In addition, you may use it to identify issues that for
some reason are particularly important for the @code{powerpc64le-linux}
system type, even if the issue affects other system types, too.

@item reproducibilidad
For issues related to reproducibility.  For example, it would be appropriate
to assign this usertag to a bug report for a package that fails to build
reproducibly.

@end table

If you're a committer and you want to add a usertag, just start using it
with the @code{guix} user.  If the usertag proves useful to you, consider
updating this section of the manual so that others will know what your
usertag means.

@node Acceso al repositorio
@section Acceso al repositorio

@cindex acceso al repositorio, para desarrolladoras
Everyone can contribute to Guix without having commit access
(@pxref{Envío de parches}).  However, for frequent contributors, having
write access to the repository can be convenient.  As a rule of thumb, a
contributor should have accumulated fifty (50) reviewed commits to be
considered as a committer and have sustained their activity in the project
for at least 6 months.  This ensures enough interactions with the
contributor, which is essential for mentoring and assessing whether they are
ready to become a committer.  Commit access should not be thought of as a
``badge of honor'' but rather as a responsibility a contributor is willing
to take to help the project.

The following sections explain how to get commit access, how to be ready to
push commits, and the policies and community expectations for commits pushed
upstream.

@subsection Applying for Commit Access

When you deem it necessary, consider applying for commit access by following
these steps:

@enumerate
@item
Encuentre tres personas que contribuyan al proyecto que puedan
respaldarle. Puede ver la lista de personas que contribuyen en
@url{https://savannah.gnu.org/project/memberlist.php?group=guix}. Cada una
de ellas deberá enviar un correo confirmando el respaldo a
@email{guix-maintainers@@gnu.org} (un alias privado para el colectivo de
personas que mantienen el proyecto), firmado con su clave OpenPGP.

Se espera que dichas personas hayan tenido algunas interacciones con usted
en sus contribuciones y sean capaces de juzgar si es suficientemente
familiar con las prácticas del proyecto. @emph{No} es un juicio sobre el
valor de su trabajo, por lo que un rechazo debe ser interpretado más bien
como un ``habrá que probar de nuevo más adelante''.

@item
Envíe un correo a @email{guix-maintainers@@gnu.org} expresando su intención,
enumerando a las tres contribuidoras que respaldan su petición, firmado con
su clave OpenPGP que usará para firmar las revisiones, y proporcionando su
huella dactilar (véase a continuación). Véase
@uref{https://emailselfdefense.fsf.org/es/} para una introducción a la
criptografía de clave pública con GnuPG.

@c See <https://sha-mbles.github.io/>.
Configure GnuPG de modo que no use el algorítmo de hash SHA1 nunca para las
firmas digitales, el cual se sabe que no es seguro desde 2019, añadiendo,
por ejemplo, la siguiente línea en @file{~/.gnupg/gpg.conf} (@pxref{GPG Esoteric Options,,, gnupg, The GNU Privacy Guard Manual}):

@example
digest-algo sha512
@end example

@item
Las personas que mantienen el proyecto decidirán en última instancia si
conceder o no el acceso de escritura, habitualmente siguiendo las
recomendaciones de las personas de referencia proporcionadas.

@item
@cindex OpenPGP, revisiones firmadas
Una vez haya conseguido acceso, en caso de hacerlo, por favor envíe un
mensaje a @email{guix-devel@@gnu.org} para notificarlo, de nuevo firmado con
la clave OpenPGP que vaya a usar para firmar las revisiones (hágalo antes de
subir su primera revisión). De esta manera todo el mundo puede enterarse y
asegurarse de que controla su clave OpenPGP.

@quotation Importante
Antes de que suba alguna revisión por primera vez, quienes mantienen Guix
deben:

@enumerate
@item
añadir su clave OpenPGP a la rama @code{keyring};
@item
añadir su firma OpenPGP al archivo @file{.guix-authorizations} de la(s)
rama(s) a las que vaya a subir código.
@end enumerate
@end quotation

@item
Asegúrese de leer el resto de esta sección y... ¡a disfrutar!
@end enumerate

@quotation Nota
Quienes mantienen el proyecto están encantadas de proporcionar acceso al
repositorio a personas que han contribuido durante algún tiempo y tienen
buen registro---¡no sea tímida y no subestime su trabajo!

No obstante, tenga en cuenta que el proyecto está trabajando hacia la
automatización de la revisión de parches y el sistema de mezclas, lo que,
como consecuencia, puede hacer necesario que menos gente tenga acceso de
escritura al repositorio principal. ¡Seguiremos informando!
@end quotation

Todas las revisiones que se suban al repositorio central de Savannah deben
estar firmadas por una clave OpenPGP, y la clave pública debe subirse a su
cuenta de usuaria en Savannah y a servidores públicos de claves, como
@code{keys.openpgp.org}. Para configurar que Git firme automáticamente las
revisiones ejecute:

@example
git config commit.gpgsign true

# Substitute the fingerprint of your public PGP key.
git config user.signingkey CABBA6EA1DC0FF33
@end example

To check that commits are signed with correct key, use:

@example
make authenticate
@end example

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

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

It additionally calls @code{make check-channel-news} to be sure
@file{news.scm} file is correct.

@subsection Commit Policy

Si obtiene acceso, por favor asegúrese de seguir la política descrita a
continuación (el debate sobre dicha política puede llevarse a cabo en
@email{guix-devel@@gnu.org}).

Los parches no triviales deben enviarse siempre a
@email{guix-patches@@gnu.org} (los parches triviales incluyen la corrección
de errores tipográficos, etcétera). Esta lista de correo rellena la base de
datos de seguimiento de parches (@pxref{Seguimiento de errores y parches}).

Para los parches que únicamente añaden un nuevo paquete, y uno simple, está
bien subirlos directamente, si tiene confianza en ello (lo que significa que
lo ha construido de manera correcta en un entorno chroot, y ha hecho un
auditado razonable de derechos de copia y licencias). Lo mismo puede ser
dicho de las actualizaciones de paquetes, excepto actualizaciones que
desencadenen muchas reconstrucciones (por ejemplo, la actualización de
GnuTLS o GLib). Tenemos una lista de correo para las notificaciones de
revisiones (@email{guix-commits@@gnu.org}), de manera que la gente pueda
enterarse. Antes de subir los cambios, asegúrese de ejecutar @code{git pull
--rebase}.

Cuando suba un commit en nombre de alguien, por favor añada una línea de
@code{Signed-off-by} al final del mensaje de la revisión---por ejemplo con
@command{git am --signoff}. Esto mejora el seguimiento sobre quién hizo qué.

Cuando añada entradas de noticias del canal (@pxref{Canales, Writing
Channel News}), compruebe que tienen el formato correcto con la siguiente
órden antes de subir los cambios al repositorio:

@example
make check-channel-news
@end example

Para cualquier otra cosa, envíe un mensaje a @email{guix-patches@@gnu.org} y
deje tiempo para que sea revisado, sin subir ningún cambio
(@pxref{Envío de parches}). Si no recibe ninguna respuesta después de dos
semanas y tiene confianza en ello, está bien subir el cambio.

Esta última parte está sujeta a revisión, para permitir a individualidades
que suban cambios que no puedan generar controversia directamente en partes
con las que estén familiarizadas.

@subsection Addressing Issues

Peer review (@pxref{Envío de parches}) and tools such as @command{guix
lint} (@pxref{Invocación de guix lint}) and the test suite (@pxref{Ejecución de la batería de pruebas}) should catch issues before they are pushed.  Yet, commits that
``break'' functionality might occasionally go through.  When that happens,
there are two priorities: mitigating the impact, and understanding what
happened to reduce the chance of similar incidents in the future.  The
responsibility for both these things primarily lies with those involved, but
like everything this is a group effort.

Some issues can directly affect all users---for instance because they make
@command{guix pull} fail or break core functionality, because they break
major packages (at build time or run time), or because they introduce known
security vulnerabilities.

@cindex reverting commits
The people involved in authoring, reviewing, and pushing such commit(s)
should be at the forefront to mitigate their impact in a timely fashion: by
pushing a followup commit to fix it (if possible), or by reverting it to
leave time to come up with a proper fix, and by communicating with other
developers about the problem.

If these persons are unavailable to address the issue in time, other
committers are entitled to revert the commit(s), explaining in the commit
log and on the mailing list what the problem was, with the goal of leaving
time to the original committer, reviewer(s), and author(s)  to propose a way
forward.

Once the problem has been dealt with, it is the responsibility of those
involved to make sure the situation is understood.  If you are working to
understand what happened, focus on gathering information and avoid assigning
any blame.  Do ask those involved to describe what happened, do not ask them
to explain the situation---this would implicitly blame them, which is
unhelpful.  Accountability comes from a consensus about the problem,
learning from it and improving processes so that it's less likely to
reoccur.

@subsection Commit Revocation

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.

Maintainers@footnote{See @uref{https://guix.gnu.org/en/about} for the
current list of maintainers.  You can email them privately at
@email{guix-maintainers@@gnu.org}.} may also revoke an individual's commit
rights, as a last resort, if cooperation with the rest of the community has
caused too much friction---even within the bounds of the project's code of
conduct (@pxref{Contribuir}).  They would only do so after public or
private discussion with the individual and a clear notice.  Examples of
behavior that hinders cooperation and could lead to such a decision include:

@itemize
@item repeated violation of the commit policy stated above;
@item repeated failure to take peer criticism into account;
@item breaching trust through a series of grave incidents.
@end itemize

When maintainers resort to such a decision, they notify developers on
@email{guix-devel@@gnu.org}; inquiries may be sent to
@email{guix-maintainers@@gnu.org}.  Depending on the situation, the
individual may still be welcome to contribute.

@subsection Helping Out

Una última cosa: el proyecto sigue adelante porque las contribuidoras no
solo suben sus cambios, sino que también ofrecen su tiempo @emph{revisando}
y subiendo cambios de otras personas. Como contribuidora, también se
agradece que use su experiencia y derechos de escritura en el repositorio
para ayudar a otras personas que quieren contribuir.

@node Actualizar el paquete Guix
@section Actualizar el paquete Guix

@cindex update-guix-package, actualización del paquete guix
A veces es deseable actualizar el propio paquete @code{guix} (el paquete
definido en @code{(gnu packages package-management)}, por ejemplo para poner
a disposición del tipo de servicio @code{guix-service-type} nuevas
características disponibles en el daemon.  Para simplificar esta tarea se
puede usar la siguiente orden:

@example
make update-guix-package
@end example

El objetivo de make @code{update-guix-package} usa la última @emph{revisión}
(commit en inglés) de @code{HEAD} en su copia local de Guix, calcula el hash
correspondiente a las fuentes de Guix en dicho commit y actualiza los campos
@code{commit}, @code{revision} y el hash de la definción del paquete
@code{guix}.

Para validar que la actualización del hash del paquete @code{guix} es
correcta y que se puede construir de manera satisfactoria se puede ejecutar
la siguiente orden en el directorio de su copia de trabajo local de Guix:

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

Para prevenir de actualizaciones accidentales del paquete @code{guix} a una
revisión a la que otras personas no puedan hacer referencia se comprueba que
dicha revisión se haya publicado ya en el repositorio git de Guix alojado en
Savannah.

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.

@cindex documentación
@node Writing Documentation
@section Writing Documentation

Guix is documented using the Texinfo system.  If you are not yet familiar
with it, we accept contributions for documentation in most formats.  That
includes plain text, Markdown, Org, etc.

Documentation contributions can be sent to @email{guix-patches@@gnu.org}.
Prepend @samp{[DOCUMENTATION]} to the subject.

When you need to make more than a simple addition to the documentation, we
prefer that you send a proper patch as opposed to sending an email as
described above.  @xref{Envío de parches} for more information on how to
send your patches.

To modify the documentation, you need to edit @file{doc/guix.texi} and
@file{doc/contributing.texi} (which contains this documentation section), or
@file{doc/guix-cookbook.texi} for the cookbook.  If you compiled the Guix
repository before, you will have many more @file{.texi} files that are
translations of these documents.  Do not modify them, the translation is
managed through @uref{https://translate.fedoraproject.org/projects/guix,
Weblate}.  @xref{Traduciendo Guix} for more information.

To render documentation, you must first make sure that you ran
@command{./configure} in your source tree (@pxref{Ejecución de Guix antes de estar instalado}).  After that you can run one of the following commands:

@itemize
@item @samp{make doc/guix.info} to compile the Info manual.
      You can check it with @command{info doc/guix.info}.
@item @samp{make doc/guix.html} to compile the HTML version.
      You can point your browser to the relevant file in the @file{doc/guix.html}
directory.
@item @samp{make doc/guix-cookbook.info} for the cookbook Info manual.
@item @samp{make doc/guix-cookbook.html} for the cookbook HTML version.
@end itemize

@cindex translation
@cindex l10n
@cindex i18n
@cindex native language support
@node Traduciendo Guix
@section Traduciendo Guix

Writing code and packages is not the only way to provide a meaningful
contribution to Guix.  Translating to a language you speak is another
example of a valuable contribution you can make.  This section is designed
to describe the translation process.  It gives you advice on how you can get
involved, what can be translated, what mistakes you should avoid and what we
can do to help you!

Guix is a big project that has multiple components that can be translated.
We coordinate the translation effort on a
@uref{https://translate.fedoraproject.org/projects/guix/,Weblate instance}
hosted by our friends at Fedora.  You will need an account to submit
translations.

Some of the software packaged in Guix also contain translations.  We do not
host a translation platform for them.  If you want to translate a package
provided by Guix, you should contact their developers or find the
information on their website.  As an example, you can find the homepage of
the @code{hello} package by typing @code{guix show hello}.  On the
``homepage'' line, you will see @url{https://www.gnu.org/software/hello/} as
the homepage.

Many GNU and non-GNU packages can be translated on the
@uref{https://translationproject.org,Translation Project}.  Some projects
with multiple components have their own platform.  For instance, GNOME has
its own platform, @uref{https://l10n.gnome.org/,Damned Lies}.

Guix has five components hosted on Weblate.

@itemize
@item @code{guix} contains all the strings from the Guix software (the
      guided system installer, the package manager, etc), excluding packages.
@item @code{packages} contains the synopsis (single-sentence description
      of a package) and description (longer description) of packages in Guix.
@item @code{website} contains the official Guix website, except for
      blog posts and multimedia content.
@item @code{documentation-manual} corresponds to this manual.
@item @code{documentation-cookbook} is the component for the cookbook.
@end itemize

@subsubheading General Directions

Once you get an account, you should be able to select a component from
@uref{https://translate.fedoraproject.org/projects/guix/,the guix project},
and select a language.  If your language does not appear in the list, go to
the bottom and click on the ``Start new translation'' button.  Select the
language you want to translate to from the list, to start your new
translation.

Like lots of other free software packages, Guix uses
@uref{https://www.gnu.org/software/gettext,GNU Gettext} for its
translations, with which translatable strings are extracted from the source
code to so-called PO files.

Even though PO files are text files, changes should not be made with a text
editor but with PO editing software.  Weblate integrates PO editing
functionality.  Alternatively, translators can use any of various
free-software tools for filling in translations, of which
@uref{https://poedit.net/,Poedit} is one example, and (after logging in)
@uref{https://docs.weblate.org/en/latest/user/files.html,upload} the changed
file.  There is also a special
@uref{https://www.emacswiki.org/emacs/PoMode,PO editing mode} for users of
GNU Emacs.  Over time translators find out what software they are happy with
and what features they need.

On Weblate, you will find various links to the editor, that will show
various subsets (or all) of the strings.  Have a look around and at the
@uref{https://docs.weblate.org/en/latest/,documentation} to familiarize
yourself with the platform.

@subsubheading Translation Components

In this section, we provide more detailed guidance on the translation
process, as well as details on what you should or should not do.  When in
doubt, please contact us, we will be happy to help!

@table @asis
@item guix
Guix is written in the Guile programming language, and some strings contain
special formatting that is interpreted by Guile.  These special formatting
should be highlighted by Weblate.  They start with @code{~} followed by one
or more characters.

When printing the string, Guile replaces the special formatting symbols with
actual values.  For instance, the string @samp{ambiguous package
specification `~a'} would be substituted to contain said package
specification instead of @code{~a}.  To properly translate this string, you
must keep the formatting code in your translation, although you can place it
where it makes sense in your language.  For instance, the French translation
says @samp{spécification du paquet « ~a » ambiguë} because the adjective
needs to be placed in the end of the sentence.

If there are multiple formatting symbols, make sure to respect the order.
Guile does not know in which order you intended the string to be read, so it
will substitute the symbols in the same order as the English sentence.

As an example, you cannot translate @samp{package '~a' has been superseded
by '~a'} by @samp{'~a' superseeds package '~a'}, because the meaning would
be reversed.  If @var{foo} is superseded by @var{bar}, the translation would
read @samp{'foo' superseeds package 'bar'}.  To work around this problem, it
is possible to use more advanced formatting to select a given piece of data,
instead of following the default English order.  @xref{Formatted Output,,,
guile, GNU Guile Reference Manual}, for more information on formatting in
Guile.

@item paquetes

Package descriptions occasionally contain Texinfo markup (@pxref{Sinopsis y descripciones}).  Texinfo markup looks like @samp{@@code@{rm -rf@}},
@samp{@@emph@{important@}}, etc.  When translating, please leave markup as
is.

The characters after ``@@'' form the name of the markup, and the text
between ``@{'' and ``@}'' is its content.  In general, you should not
translate the content of markup like @code{@@code}, as it contains literal
code that do not change with language.  You can translate the content of
formatting markup such as @code{@@emph}, @code{@@i}, @code{@@itemize},
@code{@@item}.  However, do not translate the name of the markup, or it will
not be recognized.  Do not translate the word after @code{@@end}, it is the
name of the markup that is closed at this position (e.g.@: @code{@@itemize
... @@end itemize}).

@item documentation-manual and documentation-cookbook

The first step to ensure a successful translation of the manual is to find
and translate the following strings @emph{first}:

@itemize
@item @code{version.texi}: Translate this string as @code{version-xx.texi},
      where @code{xx} is your language code (the one shown in the URL on weblate).
@item @code{contributing.texi}: Translate this string as
      @code{contributing.xx.texi}, where @code{xx} is the same language code.
@item @code{Top}: Do not translate this string, it is important for Texinfo.
      If you translate it, the document will be empty (missing a Top node).
Please look for it, and register @code{Top} as its translation.
@end itemize

Translating these strings first ensure we can include your translation in
the guix repository without breaking the make process or the @command{guix
pull} machinery.

The manual and the cookbook both use Texinfo.  As for @code{packages},
please keep Texinfo markup as is.  There are more possible markup types in
the manual than in the package descriptions.  In general, do not translate
the content of @code{@@code}, @code{@@file}, @code{@@var}, @code{@@value},
etc.  You should translate the content of formatting markup such as
@code{@@emph}, @code{@@i}, etc.

The manual contains sections that can be referred to by name by
@code{@@ref}, @code{@@xref} and @code{@@pxref}.  We have a mechanism in
place so you do not have to translate their content.  If you keep the
English title, we will automatically replace it with your translation of
that title.  This ensures that Texinfo will always be able to find the
node. If you decide to change the translation of the title, the references
will automatically be updated and you will not have to update them all
yourself.

When translating references from the cookbook to the manual, you need to
replace the name of the manual and the name of the section.  For instance,
to translate @code{@@pxref@{Defining Packages,,, guix, GNU Guix Reference
Manual@}}, you would replace @code{Defining Packages} with the title of that
section in the translated manual @emph{only} if that title is translated.
If the title is not translated in your language yet, do not translate it
here, or the link will be broken.  Replace @code{guix} with @code{guix.xx}
where @code{xx} is your language code.  @code{GNU Guix Reference Manual} is
the text of the link.  You can translate it however you wish.

@item website

The website pages are written using SXML, an s-expression version of HTML,
the basic language of the web.  We have a process to extract translatable
strings from the source, and replace complex s-expressions with a more
familiar XML markup, where each markup is numbered.  Translators can
arbitrarily change the ordering, as in the following example.

@example
#. TRANSLATORS: Defining Packages is a section name
#. in the English (en) manual.
#: apps/base/templates/about.scm:64
msgid "Packages are <1>defined<1.1>en</1.1><1.2>Defining-Packages.html</1.2></1> as native <2>Guile</2> modules."
msgstr "Pakete werden als reine <2>Guile</2>-Module <1>definiert<1.1>de</1.1><1.2>Pakete-definieren.html</1.2></1>."
@end example

Note that you need to include the same markups.  You cannot skip any.
@end table

In case you make a mistake, the component might fail to build properly with
your language, or even make guix pull fail.  To prevent that, we have a
process in place to check the content of the files before pushing to our
repository.  We will not be able to update the translation for your language
in Guix, so we will notify you (through weblate and/or by email) so you get
a chance to fix the issue.

@subsubheading Outside of Weblate

Currently, some parts of Guix cannot be translated on Weblate, help wanted!

@itemize
@item @command{guix pull} news can be translated in @file{news.scm}, but is not
      available from Weblate.  If you want to provide a translation, you can
prepare a patch as described above, or simply send us your translation with
the name of the news entry you translated and your language. @xref{Escribir de noticias del canal}, for more information about channel news.
@item Guix blog posts cannot currently be translated.
@item The installer script (for foreign distributions) is entirely in English.
@item Some of the libraries Guix uses cannot be translated or are translated
      outside of the Guix project.  Guile itself is not internationalized.
@item Other manuals linked from this manual or the cookbook might not be
      translated.
@end itemize

@subsubheading Conditions for Inclusion

There are no conditions for adding new translations of the @code{guix} and
@code{guix-packages} components, other than they need at least one
translated string.  New languages will be added to Guix as soon as
possible.  The files may be removed if they fall out of sync and have no
more translated strings.

Given that the web site is dedicated to new users, we want its translation
to be as complete as possible before we include it in the language menu.
For a new language to be included, it needs to reach at least 80%
completion.  When a language is included, it may be removed in the future if
it stays out of sync and falls below 60% completion.

The manual and cookbook are automatically added in the default compilation
target.  Every time we synchronize translations, developers need to
recompile all the translated manuals and cookbooks.  This is useless for
what is essentially the English manual or cookbook.  Therefore, we will only
include a new language when it reaches 10% completion in the component.
When a language is included, it may be removed in the future if it stays out
of sync and falls below 5% completion.

@subsubheading Translation Infrastructure

Weblate is backed by a git repository from which it discovers new strings to
translate and pushes new and updated translations.  Normally, it would be
enough to give it commit access to our repositories.  However, we decided to
use a separate repository for two reasons.  First, we would have to give
Weblate commit access and authorize its signing key, but we do not trust it
in the same way we trust guix developers, especially since we do not manage
the instance ourselves.  Second, if translators mess something up, it can
break the generation of the website and/or guix pull for all our users,
independently of their language.

For these reasons, we use a dedicated repository to host translations, and
we synchronize it with our guix and artworks repositories after checking no
issue was introduced in the translation.

Developers can download the latest PO files from weblate in the Guix
repository by running the @command{make download-po} command.  It will
automatically download the latest files from weblate, reformat them to a
canonical form, and check they do not contain issues.  The manual needs to
be built again to check for additional issues that might crash Texinfo.

Before pushing new translation files, developers should add them to the make
machinery so the translations are actually available.  The process differs
for the various components.

@itemize
@item New po files for the @code{guix} and @code{packages} components must
      be registered by adding the new language to @file{po/guix/LINGUAS} or
@file{po/packages/LINGUAS}.
@item New po files for the @code{documentation-manual} component must be
      registered by adding the file name to @code{DOC_PO_FILES} in
@file{po/doc/local.mk}, the generated @file{%D%/guix.xx.texi} manual to
@code{info_TEXINFOS} in @file{doc/local.mk} and the generated
@file{%D%/guix.xx.texi} and @file{%D%/contributing.xx.texi} to
@code{TRANSLATED_INFO} also in @file{doc/local.mk}.
@item New po files for the @code{documentation-cookbook} component must be
      registered by adding the file name to @code{DOC_COOKBOOK_PO_FILES} in
@file{po/doc/local.mk}, the generated @file{%D%/guix-cookbook.xx.texi}
manual to @code{info_TEXINFOS} in @file{doc/local.mk} and the generated
@file{%D%/guix-cookbook.xx.texi} to @code{TRANSLATED_INFO} also in
@file{doc/local.mk}.
@item New po files for the @code{website} component must be added to the
      @code{guix-artwork} repository, in @file{website/po/}.
@file{website/po/LINGUAS} and @file{website/po/ietf-tags.scm} must be
updated accordingly (see @file{website/i18n-howto.txt} for more information
on the process).
@end itemize
