README
Archivo de información del software

Captura de pantalla del archivo README de cURL

En la distribución y el desarrollo de software , un archivo README contiene información sobre los demás archivos de un directorio o archivo de software informático . Es una forma de documentación y suele ser un archivo de texto simple llamado , , , , [1] o (para indicar el uso de Markdown )READMERead MeREAD.MEREADME.txtREADME.md

El nombre del archivo generalmente se escribe en mayúsculas. En sistemas similares a Unix en particular, esto hace que se destaque, tanto porque los nombres de archivo en minúsculas son más comunes como porque el lscomando generalmente ordena y muestra los archivos en orden de código ASCII , en el que los nombres de archivo en mayúsculas aparecerán primero. [nb 1]

Contenido

Un archivo README normalmente incluye:

Historia

No está claro cuándo comenzó la convención de incluir un archivo README, pero se han encontrado ejemplos que datan de mediados de la década de 1970. [3] [4] [5] [6] [7] [8] [9] [ se necesita una mejor fuente ] El primer software del sistema Macintosh instalaba un Read Me en el disco de inicio, y los archivos README comúnmente acompañaban al software de terceros.

En particular, existe una larga historia de software libre y software de código abierto que incluye un archivo README; los Estándares de codificación GNU fomentan la inclusión de uno para proporcionar "una descripción general del paquete". [10]

Desde el advenimiento de la web como plataforma estándar de facto para la distribución de software , muchos paquetes de software han movido (o en ocasiones, copiado) algunos de los archivos auxiliares y piezas de información antes mencionados a un sitio web o wiki , a veces incluyendo el propio README o a veces dejando solo un breve archivo README sin toda la información requerida por un nuevo usuario del software.

El popular sitio web de alojamiento de código fuente GitHub recomienda encarecidamente la creación de un archivo README: si existe uno en el directorio principal (de nivel superior) de un repositorio, se presenta automáticamente en la página principal del repositorio. [11] Además del texto sin formato, también se admiten varios otros formatos y extensiones de archivo , [12] y la conversión de HTML tiene en cuenta las extensiones; en particular, README.mdse trata como GitHub Flavored Markdown .

Como término genérico

La expresión "archivo readme" también se utiliza a veces de forma genérica para otros archivos con un propósito similar. [ cita requerida ] Por ejemplo, las distribuciones de código fuente de muchos paquetes de software libre (especialmente aquellos que siguen los estándares Gnits o aquellos producidos con GNU Autotools ) incluyen un conjunto estándar de archivos readme:

READMEinformación general
AUTHORSCréditos
THANKSExpresiones de gratitud
CHANGELOGUn registro de cambios detallado, destinado a programadores.
NEWSUn registro de cambios básico, destinado a los usuarios
INSTALLInstrucciones de instalación
COPYING/LICENSEInformación sobre derechos de autor y licencias
BUGSErrores conocidos e instrucciones para informar errores nuevos
CONTRIBUTING/HACKINGGuía para posibles colaboradores del proyecto

También se distribuyen comúnmente junto con los paquetes de software un archivo de preguntas frecuentesTODO y un archivo que enumera las mejoras planificadas.

Véase también

Notas

  1. ^ Generalmente esto ya no es así, pero LC_ALL=C ls mostrará el comportamiento anterior.

Referencias

  1. ^ Raymond, Eric Steven (1996). El nuevo diccionario del hacker. MIT Press . Págs. 378-79. ISBN. 978-0-26268092-9Introducción al estilo hacker que tradicionalmente se incluye en el directorio de nivel superior de una distribución de código fuente de Unix y que contiene un puntero a documentación más detallada, créditos, historial de revisiones misceláneo, notas, etc. […] Cuando se les pregunta, los hackers invariablemente relacionan la convención README con la famosa escena de Alicia en el país de las maravillas de Lewis Carroll en la que Alicia se enfrenta a bocadillos mágicos etiquetados como "Cómeme" y "Bébeme".
  2. ^ ab Manes, Stephen (noviembre de 1996). "¿README? ¡Claro, antes de comprarlo!". PC World . 14 (11): 366.
  3. ^ "Archivo PDP-10: decus/20-0079/readme.txt de decus_20tap3_198111". pdp-10.trailing-edge.com . 1974-11-27 . Consultado el 2018-03-03 . [README.TXT es el archivo DOC para SPICE/SINC/SLIC] Esta cinta a prueba de fallos contiene los programas de análisis de circuitos SPICE SINC y SLIC descritos en el Applications Software Bulletin Volume 4. Requisitos: SPICE requiere FORTRAN-10 versión 4 debido a su uso de datos Holerith ajustados a la derecha. Se ejecuta en aproximadamente 47K. […] También incluye este archivo, el FOROTS para acompañar los SAVes y la fuente para SECOND.MAC, la rutina de temporización. SPICE se divide en tres partes: 1SPICE.FOR, 2 y 3. Hay un documento impreso para describir cada uno de los programas. Estos están incluidos en el paquete DECUS. La documentación y los programas fueron desarrollados originalmente por el departamento de Ingeniería Eléctrica de la Universidad de California en Berkeley en un CDC 6400. Excepto para convertir el FORTRAN al DECsystem-10, no se han realizado cambios en los programas. En cuanto a los datos de prueba, SLIC y SINC han mostrado una ligera variación con respecto al 6400, SPICE no muestra variación alguna. ¡Buena suerte! Ashley Grayson 27-NOV-74 [fin del README.TXT]
  4. ^ "DECUS 10-LIB-4 contiene los archivos 10-210 a 10-241, excepto 10-223". pdp-10.trailing-edge.com . 1975-03-27 . Consultado el 2018-03-03 . Los archivos de esta cinta FAILSAFE constituyen el sistema UCI LISP. En su mayor parte, están documentados en el Manual UCI LISP, disponible en el Departamento de Información y Ciencias de la Computación de la Universidad de California, Irvine, California.[1]
  5. ^ "Programmer's Workbench /sys/source/lex/README". Julio de 1977. Consultado el 25 de enero de 2020 .
  6. ^ "Unix 7th edition /usr/doc/README". 1979 . Consultado el 25 de enero de 2020 .
  7. ^ "Primer archivo usr/doc/README BSD de 32 bits". Marzo de 1980. Consultado el 25 de enero de 2020 .
  8. ^ Langemeier, Jeff (2011-07-29). "Re: Origen de README" . Consultado el 25 de enero de 2020 – a través de Stackexchange. […] tenían archivos README (archivos físicos impresos reales) para todas sus tarjetas perforadas y cintas magnéticas y prácticamente cualquier otra cosa que fuera un "programa". En ese momento, realmente necesitabas uno debido al laborioso proceso que implicaba crearlo, ejecutarlo y todo lo demás. Estos archivos README a veces también incluían las impresiones reales de cómo se suponía que debían perforarse las tarjetas perforadas como una forma de verificación y depuración de errores. La convención aparentemente también sigue el antiguo sistema en el que con todas las tarjetas perforadas se adjuntaba un "reem" de papel con la declaración README impresa en mayúsculas, que tenía todas las instrucciones de uso y carga de las tarjetas perforadas en el sistema. Como referencia temporal, esto habría sido en los años 60. […]
  9. ^ Abdelhafith, Omar (13 de agosto de 2015). «README.md: Historia y componentes». Archivado desde el original el 25 de enero de 2020. Consultado el 25 de enero de 2020 .
  10. ^ "Estándares de codificación GNU: lanzamientos". www.gnu.org . Consultado el 3 de marzo de 2018 .
  11. ^ "Acerca de los archivos README". GitHub Docs . Consultado el 31 de mayo de 2024 .
  12. ^ "Marcado". GitHub . 2014-12-25 . Consultado el 2015-02-08 .

Lectura adicional

Este artículo se basa en parte en el Jargon File , que es de dominio público.

Retrieved from "https://en.wikipedia.org/w/index.php?title=README&oldid=1251138468"