Creación de un archivo LÉAME para el repositorio

  • Artículo

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019

El repositorio Git debe tener un archivo Léame para que quienes lo vean sepan lo que hace el código y cómo pueden empezar a usarlo. El archivo Léame debe dirigirse a las siguientes audiencias:

  • Usuarios que solo quieren ejecutar el código.
  • Desarrolladores que quieren compilar y probar el código. Los desarrolladores también son usuarios.
  • Colaboradores que quieren enviar cambios al código. Los colaboradores pueden ser tanto desarrolladores como usuarios.

Escriba el archivo Léame en Markdown en lugar de con texto sin formato. Con Markdown es fácil dar formato al texto, incluir imágenes y vincular lo que haga falta para obtener más documentación del archivo Léame.

Estos son algunos archivos Léame estupendos que usan este formato y van dirigidos a las tres audiencias para tenerlos como referencia e inspiración:

Creación de una introducción

Comience el archivo Léame con una breve explicación que describa el proyecto. Si el proyecto tiene una interfaz de usuario, incluya en la introducción una captura de pantalla o GIF animado. Si el código se basa en otra aplicación o biblioteca, asegúrese de indicar esas dependencias en la introducción o justo tras ella. Si hay aplicaciones y herramientas que funcionan solo en plataformas específicas, conviene indicar las versiones de sistema operativo compatibles en esta sección del archivo Léame.

Ayudar a los usuarios a empezar

En la sección siguiente del archivo Léame, guíe a los usuarios para que pongan su código en funcionamiento en sus propios sistemas. Céntrese en los pasos esenciales para empezar a trabajar con el código. Vincule a las versiones necesarias de cualquier software de requisitos previos para que los usuarios puedan acceder fácilmente a ellas. Si existen pasos de configuración complicados, documéntelos en un lugar aparte del archivo Léame e incluya vínculos para acceder a ellos.

Señale dónde obtener la versión más reciente del código; lo mejor es un instalador binario o dejar instrucciones sobre cómo usar el código con herramientas de empaquetado. Si el proyecto es una biblioteca o una interfaz a una API, incluya un fragmento de código que refleje el uso básico y muestre la salida de ejemplo del código en ese fragmento de código.

Proporcionar pasos de compilación a desarrolladores

Use la siguiente sección del archivo Léame para enseñar a los desarrolladores a compilar el código a partir de un clon actualizado del repositorio y ejecutar cualquier prueba que se incluya. Haga lo siguiente:

  • Dé detalles sobre las herramientas necesarias para compilar el código y documente los pasos para configurarlas para conseguir una compilación limpia.
  • Divida las instrucciones de compilación densas o complejas en una página aparte de la documentación y vincule a ella si es necesario.
  • Repase las instrucciones a medida que las vaya escribiendo para constatar que funcionarían si las leyera un colaborador nuevo.

No olvide que el desarrollador que user estas instrucciones podría ser usted mismo después de algún tiempo sin trabajar en un proyecto.

Incluya los comandos para ejecutar los casos de prueba proporcionados con el código fuente después de que la compilación se realice correctamente. Los desarrolladores se apoyan en estos casos de prueba para asegurarse de que no interrumpen el código a medida que van realizando cambios. Unos casos de prueba adecuados también sirven como ejemplos que los desarrolladores pueden usar para crear sus propios casos de prueba al agregar una nueva funcionalidad.

Ayudar a los usuarios a contribuir

La última sección del archivo Léame ayuda a los usuarios y desarrolladores a participar en los informes de problemas y a sugerir ideas para mejorar el código. Los usuarios deben estar vinculados a canales en los que pueden abrir errores, solicitar características u obtener ayuda para usar el código.

Los desarrolladores deben saber qué reglas deben seguir para realizar sus aportaciones en los cambios, como las directrices de codificación/prueba y los requisitos de solicitud de incorporación de cambios. Si necesita un acuerdo de colaborador para aceptar solicitudes de incorporación de cambios o aplicar un código de conducta de la comunidad, este proceso debe estar vinculado o documentado en esta sección. Indique bajo qué licencia se publica el código y vincule al texto completo de la licencia.