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.
Servicios de Azure DevOps | Azure DevOps Server | Azure DevOps Server 2022
El repositorio de Git debe tener un archivo LÉAME para que los usuarios sepan lo que hace el código y cómo pueden empezar a usarlo. Tu archivo README debe dirigirse a los siguientes públicos:
- Usuarios que quieran ejecutar el código.
- Desarrolladores que quieren compilar y probar el código. Los desarrolladores también son usuarios.
- Colaboradores que quieran proponer cambios en tu código. Los colaboradores son desarrolladores y usuarios.
Escribe tu archivo README en Markdown en vez de texto sin formato. Markdown facilita el formato de texto, la inclusión de imágenes y el vínculo a más documentación del archivo LÉAME.
Estos son algunos archivos LÉAME que usan este formato y se dirigen a las tres audiencias. Úselos como 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. - Clonar o contribuir al código en proyectos privados: ser miembro del grupo de seguridad Contribuidores o contar con los permisos correspondientes en el proyecto. - Establecer permisos de rama o repositorio: administre permisos para la rama o el repositorio. - Establezca directivas de rama, comprobaciones de estado o cambie la rama predeterminada: edite el permiso de directivas para el repositorio o rama o la pertenencia al grupo de seguridad administradores de Project. - Importar un repositorio: miembro del grupo de seguridad de Administradores de proyecto o repositorio Git a nivel de proyecto Crear repositorio con la opción Permitir. Para obtener más información, consulte Establecimiento de permisos de repositorios Git. |
| Servicios | Repositorios habilitados. |
| Herramientas | Optional. Uso de az repos comandos: CLI de Azure DevOps. |
| Categoría | Requisitos |
|---|---|
| Acceso al proyecto | Miembro de un proyecto. |
| Permisos | - Ver código: al menos acceso básico. - Clonar o contribuir al código: Miembro de la Colaboradores grupo de seguridad o los permisos correspondientes en el proyecto. |
| Servicios | Repositorios habilitados. |
Creación de 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 solo se ejecutan 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
En la siguiente sección del archivo LÉAME, guíe a los usuarios a través de la puesta en marcha del código en su propio sistema. Manténgase centrado en los pasos esenciales para empezar a trabajar con el código. Incluye enlaces a las versiones necesarias de cualquier software previo requerido para que los usuarios puedan acceder a ellas fácilmente. Si tiene pasos complejos de configuración, documente esos pasos fuera del archivo LÉAME y vincule a ellos.
Indique a los lectores dónde obtener la versión más reciente. Proporcione uno de los siguientes elementos:
- Vínculo a un instalador binario o a un paquete precompilado.
- Instrucciones de instalación mediante un administrador de paquetes (por ejemplo, npm install, pip install o dotnet add package).
Si el proyecto es una biblioteca o un contenedor de API, incluya un fragmento de código mínimo que muestre el uso básico, seguido de la salida esperada. Esta información ayuda a los lectores a comprobar su configuración y a comprender lo que hace la biblioteca de un vistazo.
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. Siga estos pasos:
- 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 funcionan para un nuevo colaborador.
Recuerda que podrías ser el desarrollador que depende de estas instrucciones después de un tiempo sin trabajar en un proyecto.
Incluya los comandos para ejecutar los casos de prueba que se proporcionan con el código fuente después de que la compilación se realice 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 buenos casos de prueba también sirven como ejemplos que los desarrolladores pueden usar para crear sus propios casos de prueba cuando agregan nuevas funcionalidades.
Ayudar a los usuarios a contribuir
La última sección del archivo LÉAME ayuda a los usuarios y desarrolladores a participar en el informe 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 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.