@node Contribuir
@chapter Contribuir

Este proyecto es un esfuerzo colaborativo, y ¡necesitamos su ayuda para que
crezca! Por favor, contacte con nosotras en @email{guix-devel@@gnu.org} y en
@code{#guix} en la red IRC Freenode. Estamos abiertas 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::  Uso de Debbugs.
* Acceso al repositorio::    Subida de revisiones al repositorio oficial.
* Actualizar el paquete Guix::  Actualización de la definición del paquete 
                                  Guix.
@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 environment guix --pure
@end example

@xref{Invocación de guix environment}, para más información sobre dicha orden.

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 las dependencias opcionales ejecutando
@command{guix environment} con @option{--ad-hoc}:

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

Ejecute @command{./bootstrap} para generar la infraestructura del sistema de
construcción usando Autoconf y Automake. Si obtiene un error como este:

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

Una vez terminada, ejecute @command{./configure} como siempre. Asegúrese de
pasar @code{--localstatedir=@var{directorio}}, donde @var{directorio} es el
valor de @code{localstatedir} usado en su instalación actual (@pxref{El almacén}, para información sobre esto), habitualmente @file{/var}. Tenga en
cuenta que probablemente no ejecute @command{make install} para finalizar
(no tiene por qué hacerlo) pero en cualquier caso es importante proporcionar
el directorio @code{localstatedir} correcto.

Finally, you have to invoke @code{make && make check} to build Guix and run
the tests (@pxref{Ejecución de la batería de pruebas}).  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


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

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

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

@noindent
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{} y para un entorno interactivo (REPL) (@pxref{Using Guile
Interactively,,, guile, Guile Reference Manual}):

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


@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 package -i emacs guile emacs-geiser
@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
También proporcionamos plantillas para los mensajes de revisión de git
comunes y definiciones de paquetes en el directorio
@file{etc/snippets}. Estas plantillas pueden ser usadas con
@url{https://joaotavora.github.io/yasnippet, YASnippet} para expandir
mnemotécnicos a fragmentos interactivos de texto. Puedes querer añadir el
directorio de fragmentos a la variable @var{yas-snippet-dirs} en Emacs.

@lisp
;; @r{Suponiendo que la copia de trabajo de Guix está en ~/src/guix.}
(with-eval-after-load 'yasnippet
  (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets"))
@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

Una vez que se construya correctamente su paquete, por favor, envíenos un
parche (@pxref{Envío de parches}). En cualquier caso, si necesita ayuda
también estaremos felices de ayudarle. Una vez el parche se haya incorporado
al repositorio de Guix, el nuevo paquete se construye automáticamente en las
plataformas disponibles por @url{@value{SUBSTITUTE-URL}, nuestro sistema de
integración continua}.

@cindex servidor de sustituciones
Las usuarias pueden obtener la nueva definición de paquete ejecutando
simplemente @command{guix pull} (@pxref{Invocación de guix pull}). Cuando
@code{@value{SUBSTITUTE-SERVER}} ha terminado de construir el paquete, la
instalación del paquete descarga automáticamente los binarios desde allí
(@pxref{Sustituciones}). El único lugar donde la intervención humana es
necesaria es en la revisión y aplicación del parche.


@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::           Your Elisp fix.
* 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.
* Tipografías::             Amor por las letras.
@end menu

@node Libertad del software
@subsection Libertad del software

@c Adapted from http://www.gnu.org/philosophy/philosophy.html.
@cindex software 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 ue 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
A package actually has two names associated with it.  First, there is the
name of the @emph{Scheme variable}, the one following @code{define-public}.
By this name, the package can be made known in the Scheme code, for instance
as input to another package.  Second, there is the string in the @code{name}
field of a package definition.  This name is used by package management
commands such as @command{guix package} and @command{guix build}.

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

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

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{Tipografías}.


@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

Es una buena idea recortar los identificadores de revisión en el campo
@code{version} a, digamos, 7 dígitos. Esto evita una molestia estética
(asumiendo que la estética tiene importancia aquí) así como problemas
relacionados con los límites del sistema operativo como la longitud máxima
de una cadena de ejecución #! (127 bytes en el núcleo Linux). Es mejor usar
el identificador de revisión completo en @code{origin}, no obstante, para
evitar ambigüedades. Una definición típica de paquete sería así:

@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

@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
Las descripciones pueden incluir marcado Texinfo, lo que es útil para
introducir ornamentos como @code{@@code} o @code{@@dfn}, listas de puntos o
enlaces (@pxref{Overview,,, texinfo, GNU Texinfo}). Por consiguiente, debe
ser cuidadosa cuando use algunos caracteres, por ejemplo @samp{@@} y llaves,
que son los caracteres especiales básicos en Texinfo (@pxref{Special
Characters,,, texinfo, GNU Texinfo}). Las interfaces de usuaria como
@command{guix package --show} se encargan de su correcta visualización.

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

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

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

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

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

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

@cindex python
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..

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

La información de dependencias para paquetes Python está disponible
habitualmente en el árbol de fuentes, con varios grados de precisión: en el
archivo @file{setup.py}, en @file{requirements.txt} o en @file{tox.ini}.

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
Actualmente empaquetamos con @code{setuptools} y @code{pip} instalados como
Python 3.4 tiene por defecto. Por tanto no necesita especificar ninguno de
ellos como entrada. @command{guix lint} le avisará si lo hace.

@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
Los paquetes Python requeridos únicamente durante la construcción---por
ejemplo, aquellos listados con la palabra clave @code{setup_requires} en
@file{setup.py}---o únicamente para pruebas---por ejemplo, aquellos en
@code{tests_require}---van en @code{native-inputs}. La razón es que (1) no
necesitan ser propagados ya que no se requieren en tiempo de ejecución, y
(2) en un entorno de compilación cruzada lo que necesitamos es la entrada
``nativa''.

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 Tipografías
@subsection Tipografías

@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
./etc/indent-code.el gnu/packages/@var{archivo}.scm @var{paquete}
@end example

@noindent
Esto indenta automáticamente la definición de @var{paquete} en
@file{gnu/packages/@var{archivo}.scm} ejecutando Emacs en modo de
procesamiento de lotes. Para indentar un archivo completo, omita el segundo
parámetro:

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

@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

El desarrollo se lleva a cabo usando el sistema de control de versiones
distribuido Git. Por lo tanto, no es estrictamente necesario el acceso al
repositorio. Son bienvenidas las contribuciones en forma de parches como los
producidos por @code{git format-patch} enviadas a la lista de correo
@email{guix-patches@@gnu.org}. Las desarrolladoras de Guix que lleven un
tiempo en ello puede que también quieran leer la sección sobre el acceso al
repositorio (@pxref{Acceso al repositorio}).

Esta lista de correo está respaldada por una instancia de Debbugs accesible
en @uref{https://bugs.gnu.org/guix-patches}, la cual nos permite mantener el
seguimiento de los envíos. A cada mensaje enviado a esa lista de correo se
le asigna un número de seguimiento; la gente puede realizar aportaciones
sobre el tema mediante el envío de correos electrónicos a
@code{@var{NNN}@@debbugs.gnu.org}, donde @var{NNN} es el número de
seguimiento (@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
Asegúrese de que el paquete compile en su plataforma, usando @code{guix
build @var{package}}.

@item
También le recomendamos que pruebe a construir el paquete en otras
plataformas disponibles. Como puede no disponer de acceso a dichas
plataformas hardware físicamente, le recomendamos el uso de
@code{qemu-binfmt-service-type} para emularlas. Para activarlo, añada el
siguiente servicio a la lista de servicios en su configuración
@code{operating-system}:

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

Una vez hecho esto, reconfigure su sistema.

Entonces podrá construir paquetes para diferentes plataformas mediante la
opción @code{--system}. Por ejemplo, para la construcción del paquete
"hello" para las arquitecturas armhf, aarch64 o mips64 ejecutaría las
siguientes órdenes, respectivamente:
@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
Para cambios importantes, compruebe que los paquetes dependientes (si
aplica) no se ven afectados por el cambio; @code{guix refresh
--list-dependent @var{package}} le ayudará a hacerlo (@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
rama @code{staging} (cambios no disruptivos). Esta rama está pensada para
ser incorporada en @code{master} cada 6 semanas más o menos. Ramas temáticas
(por ejemplo, una actualización de la pila de GNOME) pueden ir en una rama
específica (digamos, @code{gnome-updates}).

@item más de 1.800 paquetes dependientes
rama @code{core-updates} (puede incluir cambios mayores y potencialmente
disruptivos). Esta rama está pensada para ser mezclada en @code{master} cada
6 meses más o menos.
@end table

Todas estas ramas son @uref{@value{SUBSTITUTE-URL}, seguidas por nuestra
granja de construcción} e incluidas en @code{master} una vez todo se ha
construido satisfactoriamente. Esto nos permite corregir errores antes de
que afecten a usuarias, y reducir la ventana durante la cual los binarios
preconstruidos no están disponibles.

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

Otra opción es el uso de @command{guix challenge} (@pxref{Invocación de guix challenge}). Puede ejecutarse una vez la revisión del paquete haya sido
publicada y construida por @code{@value{SUBSTITUTE-SERVER}} para comprobar
si obtuvo el mismo resultado que usted. Mejor aún: encuentre otra máquina
que pueda construirla y ejecute @command{guix publish}. Ya que la máquina
remota es probablemente diferente a la suya, puede encontrar problemas de
no-determinismo relacionados con el hardware---por ejemplo, el uso de un
conjunto de instrucciones extendido diferente---o con el núcleo del sistema
operativo---por ejemplo, dependencias en @code{uname} o archivos
@file{/proc}.

@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
Por favor, siga nuestras reglas de formato de código, posiblemente
ejecutando el guión @command{etc/indent-code.el} para que lo haga
automáticamente por usted (@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

Cuando publique un parche en la lista de correo, use @samp{[PATCH] @dots{}}
como el asunto, si su parche debe aplicarse sobre una rama distinta a
@code{master}, digamos @code{core-updates}, especifíquelo en el asunto
usando @samp{[PATCH core-updates] @dots{}}. Puede usar su cliente de correo
o la orden @command{git send-email} (@pxref{Envío de una serie de parches}). Preferimos recibir los parches en texto plano, ya sea en línea o
como adjuntos MIME. Se le recomienda que preste atención por si su cliente
de correo cambia algo como los saltos de línea o la indentación, lo que
podría potencialmente romper los parches.

Cuando un error es resuelto, por favor cierre el hilo enviando un correo a
@email{@var{NNN}-done@@debbugs.gnu.org}.

@unnumberedsubsec Envío de una serie de parches
@anchor{Envío de una serie de parches}
@cindex series de parches
@cindex @code{git send-email}
@cindex @code{git-send-email}

@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
Cuando envíe una serie de parches (por ejemplo, usando @code{git
send-email}), por favor mande primero un mensaje a
@email{guix-patches@@gnu.org}, y después mande los parches siguientes a
@email{@var{NNN}@@debbugs.gnu.org} para asegurarse de que se mantienen
juntos. Véase @uref{https://debbugs.gnu.org/Advanced.html, la documentación
de Debbugs} para más información. Puede instalar @command{git send-email}
con @command{guix install git:send-email}.

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

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

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 Acceso al repositorio
@section Acceso al repositorio

@cindex acceso al repositorio, para desarrolladoras
El acceso de escritura al repositorio es conveniente para personas que
contribuyen frecuentemente. Cuando lo crea necesario, considere solicitar
acceso al repositorio siguiendo estos pasos:

@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

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

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
git config user.signingkey CABBA6EA1DC0FF33
@end example

Puede evitar la subida accidental de revisiones sin firma a Savannah
mediante el uso del hook pre-push de Git que se encuentra en
@file{etc/git/pre-push}:

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

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.

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.

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.
