diff options
Diffstat (limited to 'doc/contributing.es.texi')
| -rw-r--r-- | doc/contributing.es.texi | 1016 |
1 files changed, 1016 insertions, 0 deletions
diff --git a/doc/contributing.es.texi b/doc/contributing.es.texi new file mode 100644 index 0000000000..05299173b6 --- /dev/null +++ b/doc/contributing.es.texi @@ -0,0 +1,1016 @@ +@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 en empaquetamiento +(@pxref{Guías 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{http://contributor-coventant.org}. Se puede encontrar una versión local +en el fichero @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. +* Guías de empaquetamiento:: Crecimiento de la distribución. +* Estilo de codificación:: Higiene de la contribuidora. +* Envío de parches:: Comparta su trabajo. +@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 + +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 (@pxref{Requisitos}). + +@itemize +@item @url{http://gnu.org/software/autoconf/, GNU Autoconf}; +@item @url{http://gnu.org/software/automake/, GNU Automake}; +@item @url{http://gnu.org/software/gettext/, GNU Gettext}; +@item @url{http://gnu.org/software/texinfo/, GNU Texinfo}; +@item @url{http://www.graphviz.org/, Graphviz}; +@item @url{http://www.gnu.org/software/help2man/, GNU Help2man (opcional)}. +@end itemize + +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 +@end example + +@xref{Invocación de guix environment}, para más información sobre esa orden. Se +pueden añadir dependencias adicionales con la opción @option{--ad-hoc}: + +@example +guix environment guix --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 fichero pkg.m4, +que proporciona pkg-config. Asegurese 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 ficheros @file{.m4} en +@file{/usr/share}. En ese caso tiene que ejecutar la siguiente orden: + +@example +export ACLOCAL_PATH=/usr/share/aclocal +@end example + +@xref{Macro Search Path,,, automake, The GNU Automake Manual} para más +información. + +Entonces, ejecute @command{./configure} como siempre. Asegurese de pasar +@code{--localstatedir=@var{directorio}}, donde @var{directorio} es el valor +de @code{localstatedir} usado por su instalación actual (@pxref{El almacén}, +para información sobre esto). + +Finalmente, tiene que ejecutar @code{make check} para iniciar las pruebas +(@pxref{Ejecución de la batería de pruebas}). Si algo falla, eche un vistazo a las +instrucciones de instalación (@pxref{Instalación}) o envíe un mensaje---en +Inglés---a la @email{guix-devel@@gnu.org, lista de correo}. + + +@node Ejecución de Guix antes de estar instalado +@section Ejecución de Guix antes de estar instalado + +Para mantener un entorno de trabajo estable, encontrará útil probar los +cambios hechos en su copia de trabajo local sin instalarlos realmente. De +esa manera, puede distinguir entre su sombrero de ``usuaria final'' y el +traje de ``harapos''. + +Para dicho fin, todas las herramientas de línea de órdenes pueden ser usadas +incluso si no ha ejecutado @code{make install}. Para hacerlo, primero +necesita tener un entorno con todas las dependencias disponibles +(@pxref{Construcción desde Git}), y entonces añada al inicio de cada orden +@command{./pre-inst-env} (el guión @file{pre-inst-env} se encuentra en la +raíz del árbol de compilación de Guix, como en@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 +$ ./pre-inst-env guix build hello +@end example + +@noindent +De manera similar, para una sesión de Guile que use los módulos Guix: + +@example +$ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))' + +;;; ("x86_64-linux") +@end example + +@noindent +@cindex REPL +@cindex entorno interactivo +@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 + +El guión @command{pre-inst-env} fija todas las variables de entorno +necesarias para permitir esto, 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{http://www.gnu.org/software/emacs, Emacs}, empoderado por el +maravilloso @url{http://nongnu.org/geiser, Geiser}. Para configurarlo, +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 ficheros 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 limpio para +Scheme. 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{http://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 ficheros 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. + + +@node Guías de empaquetamiento +@section Guías 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 ficheros @file{tar.gz} que +contienen todos los ficheros 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 +fichero 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 fichero 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{http://hydra.gnu.org/jobset/gnu/master, +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:: Ayudar a las usuarias a encontrar el paquete + adecuado. +* Módulos Python:: Un toque de comedia británica. +* Módulos Perl:: Pequeñas perlas. +* Paquetes Java:: La parada del café. +* Tipografías:: Amor por las letras. +@end menu + +@node Libertad del software +@subsection Libertad del software + +@c =========================================================================== +@c +@c This file was generated with po4a. Translate the source file. +@c +@c =========================================================================== +@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{http://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 proporcionan únicamente software que permite estas cuatro +libertades. + +Además, la distribución GNU sigue las +@url{http://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 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 @code{origin} del paquete (@pxref{Definición de paquetes}). De +este modo, @code{guix build --source} devuelve las fuentes ``liberadas'' en +vez de la versión original de las fuentes. + + +@node Nombrado de paquetes +@subsection Nombrado de paquetes + +@cindex nombre de paquete +Un paquete tiene realmente dos nombres asociados con él: Primero, el nombre +de la @emph{variable Scheme} asociada, que aparece después de +@code{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 @code{name} de la definición de paquete. Este nombre se usa por +las órdenes de gestión de paquetes como @command{guix package} y +@command{guix build}. + +Ambos normalmente son iguales y corresponden a la conversión a minúsculas +del nombre de proyecto elegido por sus creadoras, con los guiones bajos +sustituidos por guiones. Por ejemplo, GNUnet está disponible como +@code{gnunet}, y SDL_net como @code{sdl-net}. + +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: + +@example +(define-public gtk+ + (package + (name "gtk+") + (version "3.9.12") + ...)) +(define-public gtk+-2 + (package + (name "gtk+") + (version "2.24.20") + ...)) +@end example +Si también deseásemos GTK+3.8.2, se empaquetaría como +@example +(define-public gtk+-3.8 + (package + (name "gtk+") + (version "3.8.2") + ...)) +@end example + +@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 tamié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í: + +@example +(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 example + +@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 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@tie{}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. + +@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. + +Las sinopsis y descripciones son traducidas por voluntarias +@uref{http://translationproject.org/domain/guix-packages.html, en +Translation Project} 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 @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}): + +@example +;; 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 example + + +@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 compila sólo con Python 3, lo llamamos +@code{python-foo}; si compila sólo con Python 2, lo llamamos +@code{python2-foo}. Si es compatible con ambas versiones, creamos dos +paquetes con los nombres correspondientes. + +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 +fichero @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 fichero +@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 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. + +El código de Guix debe definir tipos de datos apropiados (por ejemplo, +mediante el uso @code{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 @code{(ice-9 match)}, especialmente cuando se analizan listas. + +@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{http://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 fichero @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{fichero}.scm @var{paquete} +@end example + +@noindent +Esto indenta automáticamente la definición de @var{paquete} en +@file{gnu/packages/@var{fichero}.scm} ejecutando Emacs en modo de +procesamiento de lotes. Para indentar un fichero completo, omita el segundo +parámetro: + +@example +./etc/indent-code.el gnu/services/@var{fichero}.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}. + +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 fichero 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 +Asegurese 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}: + +@example +(service qemu-binfmt-service-type + (qemu-binfmt-configuration + (platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el")) + (guix-support? #t))) +@end example + +Una vez hecho esto, reconfigure su sistema. + +Enotonces 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 +guix build --system=mips64el-linux --rounds=2 hello +@end example + +@item +@cindex empaquetamientos +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. + +@item +Eche un vistazo al perfil mostrado por @command{guix size} (@pxref{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 (@pxref{Paquetes con múltiples salidas}), y qué +dependencias opcionales deben usarse. En particular, evite añadir +@code{texlive} como una dependencia: debido a su tamaño extremo, use +@code{texlive-tiny} o @code{texlive-union}. + +@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.200 paquetes dependientes +rama @code{staging} (cambios no disruptivos). Esta rama está pensada para +ser incorporada en @code{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, @code{gnome-updates}). + +@item más de 1.200 paquetes dependientes +rama @code{core-updates} (puede incluir cambios mayores y potencialmente +disruptivos). Esta rama está pensada para ser incluida en @code{master} cada +2,5 más o menos. +@end table + +Todas estas ramas son @uref{https://hydra.gnu.org/project/gnu, 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. +Generalmente, ramas distintas a @code{master} se consideran +@emph{congeladas} si ha habido una evaluación reciente, o hay una rama +@code{-next} correspondiente. Por favor, pregunte en la lista de correo o en +IRC si no está segura de dónde colocar un parche. + +@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 ficheros +@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 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 +@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. + +@end enumerate + +Cuando publique un parche a la lista de correo, use @samp{[PATCH] @dots{}} +como el asunto. 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. |