diff options
Diffstat (limited to 'doc/contributing.es.texi')
| -rw-r--r-- | doc/contributing.es.texi | 1016 |
1 files changed, 0 insertions, 1016 deletions
diff --git a/doc/contributing.es.texi b/doc/contributing.es.texi deleted file mode 100644 index 05299173b6..0000000000 --- a/doc/contributing.es.texi +++ /dev/null @@ -1,1016 +0,0 @@ -@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. |