Contribuir
**********

Este proyecto es un esfuerzo colaborativo, y ¡necesitamos su ayuda para que crezca! Por favor, contacte con nosotras en guix-devel@gnu.org y en #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 en empaquetamiento (see Guías de empaquetamiento).

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 http://contributor-coventant.org. Se puede encontrar una versión local en el fichero 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.

Construcción desde Git
======================

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

     git clone https://git.savannah.gnu.org/git/guix.git

Cuando se compila Guix de una copia de trabajo local (checkout), se requieren los siguientes paquetes, además de los mencionados en las instrucciones de instalación (see Requisitos).

  * GNU Autoconf (http://gnu.org/software/autoconf/);

  * GNU Automake (http://gnu.org/software/automake/);

  * GNU Gettext (http://gnu.org/software/gettext/);

  * GNU Texinfo (http://gnu.org/software/texinfo/);

  * Graphviz (http://www.graphviz.org/);

  * GNU Help2man (opcional) (http://www.gnu.org/software/help2man/).

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:

     guix environment guix

See Invocación de guix environment, para más información sobre esa orden. Se pueden añadir dependencias adicionales con la opción --ad-hoc:

     guix environment guix --ad-hoc help2man git strace

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

     configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES

probablemente significa que Autoconf no pudo encontrar el fichero pkg.m4, que proporciona pkg-config. Asegurese de que pkg.m4 está disponible. Lo mismo aplica para el conjunto de macros guile.m4 que proporciona Guile. Por ejemplo, si ha instalado Automake en /usr/local, no va a buscar ficheros .m4 en /usr/share. En ese caso tiene que ejecutar la siguiente orden:

     export ACLOCAL_PATH=/usr/share/aclocal

See Macro Search Path (The GNU Automake Manual) para más información.

Entonces, ejecute ./configure como siempre. Asegurese de pasar --localstatedir=DIRECTORIO, donde DIRECTORIO es el valor de localstatedir usado por su instalación actual (see El almacén, para información sobre esto).

Finalmente, tiene que ejecutar make check para iniciar las pruebas (see Ejecución de la batería de pruebas). Si algo falla, eche un vistazo a las instrucciones de instalación (see Instalación) o envíe un mensaje---en Inglés---a la lista de correo.

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 órdenes pueden ser usadas incluso si no ha ejecutado make install. Para hacerlo, primero necesita tener un entorno con todas las dependencias disponibles (see Construcción desde Git), y entonces añada al inicio de cada orden ./pre-inst-env (el guión pre-inst-env se encuentra en la raíz del árbol de compilación de Guix, como en (La opción -E a sudo asegura que GUILE_LOAD_PATH contiene la información correcta para que guix-daemon y las herramientas que usa puedan encontrar los módulos Guile que necesitan.):

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

De manera similar, para una sesión de Guile que use los módulos Guix:

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

     ;;; ("x86_64-linux")

... y para un entorno interactivo (REPL) (see Using Guile Interactively (Guile Reference Manual)):

     $ ./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

El guión pre-inst-env fija todas las variables de entorno necesarias para permitir esto, incluyendo PATH y GUILE_LOAD_PATH.

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

La configuración perfecta
=========================

La configuración perfecta para hackear en Guix es básicamente la configuración perfecta para hacerlo en Guile (see Using Guile in Emacs (Guile Reference Manual)). Primero, necesita más que un editor, necesita Emacs (http://www.gnu.org/software/emacs), empoderado por el maravilloso Geiser (http://nongnu.org/geiser). Para configurarlo, ejecute:

     guix package -i emacs guile emacs-geiser

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, M-. para saltar a la definición de un objeto, una consola interactiva (REPL) para probar su código, y más (see Introducción (Geiser User Manual)). Para desarrollar Guix adecuadamente, asegúrese de aumentar la ruta de carga de Guile (load-path) para que encuentre los ficheros fuente de su copia de trabajo:

     ;; 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"))

Para realmente editar el código, Emacs tiene un modo limpio para Scheme. Pero además de eso, no debe perderse Paredit (http://www.emacswiki.org/emacs/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.

También proporcionamos plantillas para los mensajes de revisión de git comunes y definiciones de paquetes en el directorio etc/snippets. Estas plantillas pueden ser usadas con YASnippet (http://joaotavora.github.io/yasnippet) para expandir mnemotécnicos a fragmentos interactivos de texto. Puedes querer añadir el directorio de fragmentos a la variable YAS-SNIPPET-DIRS en Emacs.

     ;; 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"))

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

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

Guías de empaquetamiento
========================

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 archivadores de código fuente---típicamente ficheros tar.gz que contienen todos los ficheros fuente. Añadir un paquete a la distribución significa esencialmente dos cosas: añadir una receta que describe cómo construir el paquete, la que incluye una lista de otros paquetes necesarios para la construcción, y añadir 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 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 (see Módulos de paquetes). No obstante, un conocimiento profundo de Scheme no es un pre-requisito para la creación de paquetes. Para más información obre las definiciones de paquetes, see Definición de paquetes.

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

     ./pre-inst-env guix build gnuevo --keep-failed

El uso de --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 --log-file, para acceder al log de construcción.

Si el paquete resulta desconocido para la orden guix, puede ser que el fichero fuente contenga un error de sintaxis, o no tenga una cláusula 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:

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

Una vez que se construya correctamente su paquete, por favor, envíenos un parche (see 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 nuestro sistema de integración continua (http://hydra.gnu.org/jobset/gnu/master).

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

Libertad del software
---------------------

El sistema operativo GNU se ha desarrollado para que las usuarias puedan ejercitar su libertad de computación. GNU es software libre, lo que significa ue las usuarias tienen las cuatro libertades esenciales (http://www.gnu.org/philosophy/free-sw.html): 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 proporcionan únicamente software que permite estas cuatro libertades.

Además, la distribución GNU sigue las directrices de distribución de software libre (http://www.gnu.org/distros/free-system-distribution-guidelines.html). Entre otras cosas, estas directrices rechazan firmware no-libre, recomendaciones de software no-libre y el tratamiento de 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 origin del paquete (see Definición de paquetes). De este modo, guix build --source devuelve las fuentes ``liberadas'' en vez de la versión original de las fuentes.

Nombrado de paquetes
--------------------

Un paquete tiene realmente dos nombres asociados con él: Primero, el nombre de la variable Scheme asociada, que aparece después de define-public. A través de este nombre, el paquete está disponible en código Scheme, por ejemplo como entrada de otro paquete. Segundo, la cadena en el campo name de la definición de paquete. Este nombre se usa por las órdenes de gestión de paquetes como guix package y 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 gnunet, y SDL_net como sdl-net.

No añadimos prefijos lib para paquetes de bibliotecas, a menos que sean parte del nombre oficial del proyecto. Pero vea Módulos Python y 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, see Tipografías.

Versiones numéricas
-------------------

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 Nombrado de paquetes para la versión más reciente; las versiones previas usan el mismo nombre, añadiendo un - 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:

     (define-public gtk+
       (package
         (name "gtk+")
         (version "3.9.12")
         ...))
     (define-public gtk+-2
       (package
         (name "gtk+")
         (version "2.24.20")
         ...))

Si también deseásemos GTK+3.8.2, se empaquetaría como

     (define-public gtk+-3.8
       (package
         (name "gtk+")
         (version "3.8.2")
         ...))

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 version?

Claramente, tenemos que hacer visible el identificador de la revisión en el VCS en la cadena de versión, pero tamién debemos asegurarnos que la cadena de versión incrementa monotónicamente de manera que 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í:

     2.0.11-3.cabba9e
       ^    ^    ^
       |    |    `-- ID de revisión original
       |    |
       |    `--- revisión del paquete Guix
       |
     última versión de publicación

Es una buena idea recortar los identificadores de revisión en el campo 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 origin, no obstante, para evitar ambigüedades. Una definición típica de paquete sería así:

     (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..."))
                     (file-name (git-file-name name version))))
           ;; ...
           )))

Sinopsis y descripciones
------------------------

Como hemos visto previamente, cada paquete en GNU Guix incluye una sinopsis y una descripción (see Definición de paquetes). Las sinopsis y descripciones son importantes: son en lo que 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 ficheros''. La sinopsis debe decir qué es el paquete---por ejemplo, ``Utilidades básicas GNU (ficheros, texto, shell)''---o para qué se usa---por ejemplo, la sinopsis de GNU grep es ``Imprime líneas que 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 esperablemente proporciona 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.

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

Las sinopsis y descripciones son traducidas por voluntarias en Translation Project (http://translationproject.org/domain/guix-packages.html) para que todas las usuarias posibles puedan leerlas en su lengua nativa. Las interfaces de usuaria las buscan y las muestran en el idioma especificado por la localización actual.

Para permitir a xgettext extraerlas como cadenas traducibles, las sinopsis y descripciones deben ser cadenas literales. Esto significa que no puede usar string-append o format para construir estas cadenas:

     (package
       ;; ...
       (synopsis "Esto es traducible")
       (description (string-append "Esto " "*no*" " es traducible.")))

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 (see xgettext Invocation (GNU Gettext)):

     ;; 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. ...")

Módulos Python
--------------

Actualmente empaquetamos Python 2 y Python 3, bajo los nombres de variable Scheme python-2 y python como se explica en 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 python.

Algunos módulos son compatibles únicamente con una versión de Python, otros con ambas. Si el paquete Foo compila sólo con Python 3, lo llamamos python-foo; si compila sólo con Python 2, lo llamamos python2-foo. Si es compatible con ambas versiones, creamos dos paquetes con los nombres correspondientes.

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

Especificación de dependencias
..............................

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

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

  * Actualmente empaquetamos con setuptools y pip instalados como Python 3.4 tiene por defecto. Por tanto no necesita especificar ninguno de ellos como entrada. guix lint le avisará si lo hace.

  * Las dependencias Python requeridas en tiempo de ejecución van en propagated-inputs. Típicamente están definidas con la palabra clave install_requires en setup.py, o en el fichero requirements.txt.

  * Los paquetes Python requeridos únicamente durante la construcción---por ejemplo, aquellos listados con la palabra clave setup_requires en setup.py---o únicamente para pruebas---por ejemplo, aquellos en tests_require---van en 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 pytest, mock y nose. Por supuesto, si alguno de estos paquetes también se necesita en tiempo de ejecución, necesita ir en propagated-inputs.

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

  * Si un paquete Python tiene dependencias opcionales (extras_require), queda en su mano decidir si las añade o no, en base a la relación utilidad/sobrecarga (see guix size).

Módulos 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 :: por guiones y agregando el prefijo perl-. Por tanto la clase XML::Parser se convierte en perl-xml-parser. Los módulos que contienen varias clases mantienen su nombre oficial en minúsculas y también se agrega perl- al inicio. Dichos módulos tienden a tener la palabra perl en alguna parte de su nombre, la cual se elimina en favor del prefijo. Por ejemplo, libwww-perl se convierte en perl-libwww.

Paquetes 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 java-. Si el proyecto ya tiene la palabra java, eliminamos esta; por ejemplo, el paquete ngsjaga se empaqueta bajo el nombre 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 . por guiones y agregando el prefijo java-. Por tanto la clase apache.commons.cli se convierte en el paquete java-apache-commons-cli.

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 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 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 font-liberation-sans, etcétera; pero como se distribuyen de forma conjunta bajo un nombre común, preferimos empaquetarlas conjuntamente como 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 -ttf para tipografías TrueType, -otf para tipografías OpenType y -type1 para tipografías Tipo 1 PostScript.

Estilo de codificación
======================

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

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

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 (guix build ...). 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 (gnu ...) en vez de en (guix ...).

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 car, cdr, 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.

El código de Guix debe definir tipos de datos apropiados (por ejemplo, mediante el uso define-record-type*) en vez de abusar de las listas. Además debe usarse el reconocimiento de patrones, vía el módulo de Guile (ice-9 match), especialmente cuando se analizan listas.

Formato del código
------------------

Cuando escribimos código Scheme, seguimos la sabiduría común entre las programadoras Scheme. En general, seguimos las Reglas de estilo Lisp de Riastradh (http://mumble.net/~campbell/scheme/style.txt). 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 substitute* tienen reglas de indentación especiales. Estas están definidas en el fichero .dir-locals.el, el cual Emacs usa automáticamente. Fíjese que además Emacs-Guix proporciona el modo guix-devel-mode que indenta y resalta adecuadamente el código de Guix (see Desarrollo (The Emacs-Guix Reference Manual)).

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:

     ./etc/indent-code.el gnu/packages/FICHERO.scm PAQUETE

Esto indenta automáticamente la definición de PAQUETE en gnu/packages/FICHERO.scm ejecutando Emacs en modo de procesamiento de lotes. Para indentar un fichero completo, omita el segundo parámetro:

     ./etc/indent-code.el gnu/services/FICHERO.scm

Si está editando código con Vim, le recomendamos ejecutar :set autoindent para que el código se indente automáticamente mientras escribe. Adicionalmente, paredit.vim (https://www.vim.org/scripts/script.php?script_id=3998) 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 (guix build ...) 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.

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 git format-patch enviadas a la lista de correo guix-patches@gnu.org.

Esta lista de correo está respaldada por una instancia de Debbugs accesible en 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 NNN@debbugs.gnu.org, donde NNN es el número de seguimiento (see Envío de una serie de parches).

Le rogamos que escriba los mensajes de revisiones en formato ChangeLog (see Change Logs (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:

 1. 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 fichero de firma GPG separado esto puede hacerse con la orden gpg --verify.

 2. Dedique algún tiempo a proporcionar una sinopsis y descripción adecuadas para el paquete. See Sinopsis y descripciones, para algunas directrices.

 3. Ejecute guix lint PAQUETE, donde PAQUETE es el nombre del paquete nuevo o modificado, y corrija cualquier error del que informe (see Invocación de guix lint).

 4. Asegurese de que el paquete compile en su plataforma, usando guix build PACKAGE.

 5. 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 qemu-binfmt-service-type para emularlas. Para activarlo, añada el siguiente servicio a la lista de servicios en su configuración operating-system:

          (service qemu-binfmt-service-type
           (qemu-binfmt-configuration
             (platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el"))
             (guix-support? #t)))

     Una vez hecho esto, reconfigure su sistema.

     Enotonces podrá construir paquetes para diferentes plataformas mediante la opción --system. Por ejemplo, para la construcción del paquete "hello" para las arquitecturas armhf, aarch64 o mips64 ejecutaría las siguientes órdenes, respectivamente:

          guix build --system=armhf-linux --rounds=2 hello
          guix build --system=aarch64-linux --rounds=2 hello
          guix build --system=mips64el-linux --rounds=2 hello

 6. Asegurese 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.

 7. Eche un vistazo al perfil mostrado por guix size (see Invocación de guix size). Esto le permitirá darse cuenta de referencias a otros paquetes retenidas involuntariamente. También puede ayudar a determinar si se debe dividir el paquete (see Paquetes con múltiples salidas), y qué dependencias opcionales deben usarse. En particular, evite añadir texlive como una dependencia: debido a su tamaño extremo, use texlive-tiny o texlive-union.

 8. Para cambios importantes, compruebe que los paquetes dependientes (si aplica) no se ven afectados por el cambio; guix refresh --list-dependent PACKAGE le ayudará a hacerlo (see Invocación de guix refresh).

     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:

     300 paquetes dependientes o menos
          rama master (cambios no disruptivos).

     entre 300 y 1.200 paquetes dependientes
          rama staging (cambios no disruptivos). Esta rama está pensada para ser incorporada en master cada 3 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, gnome-updates).

     más de 1.200 paquetes dependientes
          rama core-updates (puede incluir cambios mayores y potencialmente disruptivos). Esta rama está pensada para ser incluida en master cada 2,5 más o menos.

     Todas estas ramas son seguidas por nuestra granja de construcción (https://hydra.gnu.org/project/gnu) e incluidas en 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.

     Generalmente, ramas distintas a master se consideran congeladas si ha habido una evaluación reciente, o hay una rama -next correspondiente. Por favor, pregunte en la lista de correo o en IRC si no está segura de dónde colocar un parche.

 9. 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 (see Invocación de guix build):

          guix build --rounds=2 mi-paquete

     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 guix challenge (see Invocación de guix challenge). Puede ejecutarse una vez la revisión del paquete haya sido publicada y construida por SUBSTITUTE-SERVER para comprobar si obtuvo el mismo resultado que usted. Mejor aún: encuentre otra máquina que pueda construirla y ejecute 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 uname o ficheros /proc.

 10. Cuando escriba documentación, por favor use construcciones neutrales de género para referirse a la gente (NdT: En esta traducción se ha optado por usar el femenino para referirse a 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 lecura 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 singular ``they'', ``their'', ``them'' (https://en.wikipedia.org/wiki/Singular_they) y demás.

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

 12. Por favor, siga nuestras reglas de formato de código, posiblemente ejecutando el guión etc/indent-code.el para que lo haga automáticamente por usted (see Formato del código).

 13. Cuando sea posible, use espejos en la URL de las fuentes (see 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 name en la URL: no es muy útil y si el nombre cambia, la URL probablemente estará mal.

Cuando publique un parche a la lista de correo, use [PATCH] ... como el asunto. Puede usar su cliente de correo o la orden git send-email (see 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 NNN-done@debbugs.gnu.org.

Envío de una serie de parches
-----------------------------

Cuando envíe una serie de parches (por ejemplo, usando git send-email), por favor mande primero un mensaje a guix-patches@gnu.org, y después mande los parches siguientes a NNN@debbugs.gnu.org para asegurarse de que se mantienen juntos. Véase la documentación de Debbugs (https://debbugs.gnu.org/Advanced.html) para más información.