Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022
El repositorio de Git debe tener un archivo Léame para que los espectadores sepan lo que hace el código y cómo pueden empezar a usarlo. El léame debe hablar con las audiencias siguientes:
- 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 son desarrolladores y usuarios.
Escriba el archivo Léame en Markdown en lugar de texto sin formato. Markdown facilita el formato de texto, incluir imágenes y vincular según sea necesario para obtener más documentación del archivo Léame.
Estos son algunos excelentes léames que usan este formato y hablan a las tres audiencias, por referencia e inspiración:
Prerrequisitos
| Categoría | Requisitos |
|---|---|
| Acceso al proyecto | Miembro de un proyecto. |
| Permisos | - Ver código en proyectos privados: al menos acceso básico . - Clone o contribuya al código en proyectos privados: miembro del grupo de seguridad Colaboradores o de los permisos correspondientes del proyecto. - Establecer permisos de rama o repositorio: administre permisos para la rama o el repositorio. - Cambiar la rama predeterminada: edite los permisos de directivas para el repositorio. - Importar un repositorio: miembro del grupo de seguridad Administradores de proyectos o del nivel de proyecto de Git Crear conjunto de permisos de repositorio en Permitir. Para obtener más información, consulte Establecimiento de permisos de repositorios Git. |
| Servicios | Repositorios habilitados. |
| Herramientas | Optional. Use los comandos az repos : CLI de Azure DevOps. |
Nota:
En proyectos públicos, los usuarios con acceso a las partes interesadas tienen acceso completo a Azure Repos, incluida la visualización, la clonación y la contribución al código.
| Categoría | Requisitos |
|---|---|
| Acceso al proyecto | Miembro de un proyecto. |
| Permisos | - Ver código: al menos acceso básico . - Clone o contribuya al código: miembro del grupo de seguridad Colaboradores o de los permisos correspondientes del proyecto. |
| Servicios | Repositorios habilitados. |
Crear una introducción
Comience el archivo Léame con una breve explicación que describa el proyecto. Agregue una captura de pantalla o GIF animado en la introducción si el proyecto tiene una interfaz de usuario. Si el código se basa en otra aplicación o biblioteca, asegúrese de indicar esas dependencias en la introducción o justo debajo de ella. Las aplicaciones y herramientas que se ejecutan solo en plataformas específicas deben tener las versiones de sistema operativo compatibles que se indican en esta sección del archivo Léame.
Ayudar a los usuarios a empezar
Guía a los usuarios a través de la puesta en marcha del código en su propio sistema en la sección siguiente del archivo Léame. Manténgase centrado 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 ellos. Si tiene pasos complejos de configuración, documente los que están fuera del archivo Léame y vincule a ellos.
Indique dónde obtener la versión más reciente del código. Un instalador binario o instrucciones sobre cómo usar el código mediante herramientas de empaquetado es mejor. Si el proyecto es una biblioteca o una interfaz de una API, coloque un fragmento de código que muestre el uso básico y muestre la salida de ejemplo del código en ese fragmento de código.
Proporcionar pasos de compilación para desarrolladores
Use la siguiente sección del archivo Léame para mostrar a los desarrolladores cómo compilar el código a partir de un clon nuevo del repositorio y ejecutar las pruebas incluidas. Haga lo siguiente:
- Proporcione detalles sobre las herramientas necesarias para compilar el código y documentar los pasos para configurarlos para obtener una compilación limpia.
- Divida las instrucciones de compilación densas o complejas en una página independiente de la documentación y vincule a ella si es necesario.
- Ejecute las instrucciones mientras las escribe para comprobar que las instrucciones funcionarían para un nuevo colaborador.
Recuerde que el desarrollador que confía en estas instrucciones podría ser usted después de no trabajar en un proyecto durante algún tiempo.
Proporcione los comandos para ejecutar los casos de prueba proporcionados con el código fuente después de que la compilación se haya realizado correctamente. Los desarrolladores se basan en estos casos de prueba para asegurarse de que no interrumpen el código a medida que realizan cambios. Los 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 involucrarse en los problemas de informes y sugerir ideas para mejorar el código. Los usuarios deben estar vinculados a canales en los que pueden abrir errores, solicitar características o obtener ayuda con el código.
Los desarrolladores deben saber qué reglas deben seguir para contribuir a los cambios, como las directrices de codificación y pruebas y los requisitos de solicitud de incorporación de cambios. Si necesita un contrato 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 en qué licencia se publica el código y vincule al texto completo de la licencia.