Flujo de trabajo de desarrollo 💻#

Esta guía explica cómo los empleados y colaboradores de Ultralytics planifican, implementan, revisan, prueban y fusionan cambios en los proyectos de Ultralytics, incluidos YOLO y otros repositorios relacionados.

El flujo de trabajo es deliberadamente ligero: mantén los cambios centrados, facilita la revisión, ejecuta las comprobaciones adecuadas y deja suficiente contexto para que tus compañeros entiendan la decisión más adelante.

Código de conducta 🤝#

Todos los colaboradores deben seguir el Código de conducta. Se espera respeto, claridad y profesionalidad en las incidencias, los PR, las revisiones, los debates internos y los espacios públicos de la comunidad. Para conocer los requisitos de colaboración pública, consulta la Guía oficial de contribución.

Ritmo de colaboración 🛰️#

• Días de coordinación (martes/miércoles/jueves): Usa estos días para revisiones de código, debates de diseño, sesiones de depuración y decisiones que se beneficien de la colaboración síncrona.
• Lunes/viernes: Prioriza el trabajo concentrado, las actualizaciones por escrito, la preparación de PR y la revisión asíncrona. Traslada los bloqueos críticos al siguiente día de coordinación cuando sea necesaria una puesta en común síncrona.
• Reuniones diarias y revisiones: Limita las reuniones diarias a 15 minutos. Programa las revisiones de diseño y arquitectura en los días de coordinación siempre que sea posible.
• Registros de decisiones: Documenta las decisiones importantes en las descripciones de PR, las incidencias, la documentación o los runbooks para que el contexto no desaparezca en el chat.

Alcance y responsabilidad 🧭#

Este flujo de trabajo se aplica al trabajo de ingeniería de Ultralytics en producto, Ultralytics Platform, YOLO, infraestructura, documentación, automatización y sistemas sensibles desde el punto de vista de la seguridad. Cada repositorio puede añadir requisitos más estrictos, pero no debería relajar las expectativas básicas de esta página.

Cada elemento de trabajo debe tener una persona responsable clara:

• Autor: Implementa el cambio, mantiene actualizado el PR y proporciona pruebas de validación.
• Revisor: Confirma la corrección, la mantenibilidad, el riesgo y el impacto en la documentación.
• Responsable del área: Revisa los cambios que afectan a un área especializada, como el comportamiento del modelo, la infraestructura, la seguridad, la privacidad, las licencias o los flujos de trabajo orientados al cliente.
• Responsable de triaje: Asigna las incidencias, los incidentes, los informes de vulnerabilidades y las tareas de mantenimiento entrantes a la persona responsable adecuada.

Proceso de Pull Request 🔄#

flowchart TD
    A[Fork or Sync Repository]:::start --> B[Create Feature Branch]:::proc
    B --> C[Make Changes]:::proc
    C --> D[Run Tests Locally]:::proc
    D --> E[Commit Changes]:::proc
    E --> F[Create Pull Request]:::proc
    F --> G[Sign CLA]:::proc
    G --> H{Review}:::decide
    H -->|Changes Requested| I[Address Feedback]:::proc
    I --> H
    H -->|Approved| J[Merge!]:::out

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef decide fill:#FF9800,color:#fff
    classDef out fill:#9C27B0,color:#fff

1. Haz un fork o sincroniza el repositorio#

Los colaboradores externos deben hacer un fork del repositorio de Ultralytics correspondiente, como ultralytics/ultralytics, en su cuenta de GitHub.

Los empleados con acceso de escritura deben sincronizar main antes de crear una rama:

# External contributors
git clone https://github.com/YOUR_USERNAME/ultralytics.git
cd ultralytics

# Employees with write access
git checkout main
git pull origin main

2. Crea una rama de funcionalidad#

Crea una rama con un nombre claro y descriptivo que refleje el trabajo:

git checkout -b fix-issue-123

3. Realiza los cambios#

4. Prueba los cambios#

pytest tests/

Más información: Requisitos de pruebas, Validación de modelos, Flujos de trabajo de CI

5. Confirma los cambios#

Crea un commit con mensajes concisos y descriptivos:

git commit -m "Fix #123: Corrected calculation error"

6. Crea un Pull Request#

Envía un PR desde tu rama a main:

7. Firma el CLA#

Después de enviar tu PR, añade este comentario:

El bot del CLA te guiará durante el proceso. Para obtener más información sobre las licencias, consulta nuestra guía de contribución.

8. Responde a los comentarios de la revisión#

Responde a los comentarios de los revisores, sube las actualizaciones y mantén al día la descripción del PR si cambia el alcance. Resuelve todos los comentarios bloqueantes antes de solicitar una nueva revisión.

Docstrings al estilo de Google 📝#

Las funciones y clases públicas deben usar docstrings al estilo de Google cuando el repositorio lo requiera. Mantén las docstrings precisas, concisas y útiles para quienes mantengan el código en el futuro.

Función estándar#

def example_function(arg1, arg2=4):
    """Example function demonstrating Google-style docstrings.

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument.

    Returns:
        (bool): True if arguments are equal, False otherwise.

    Examples:
        >>> example_function(4, 4)  # True
        >>> example_function(1, 2)  # False
    """
    return arg1 == arg2

Valores devueltos con nombre#

def example_function(arg1, arg2=4):
    """Example function with named return.

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument.

    Returns:
        equals (bool): True if arguments are equal, False otherwise.

    Examples:
        >>> example_function(4, 4)  # True
    """
    equals = arg1 == arg2
    return equals

Múltiples valores devueltos#

def example_function(arg1, arg2=4):
    """Example function with multiple returns.

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument.

    Returns:
        equals (bool): True if arguments are equal, False otherwise.
        added (int): Sum of both input arguments.

    Examples:
        >>> equals, added = example_function(2, 2)  # True, 4
    """
    equals = arg1 == arg2
    added = arg1 + arg2
    return equals, added

Importante: Cuando una función devuelve varios valores, documenta cada valor devuelto por separado en lugar de ocultar detalles importantes dentro de una descripción genérica de tupla.

✅ Correcto:

Returns:
    (np.ndarray): Predicted masks with shape HxWxN.
    (list): Confidence scores for each instance.

❌ Incorrecto:

Returns:
    (tuple): Tuple containing:
        - (np.ndarray): Predicted masks with shape HxWxN.
        - (list): Confidence scores for each instance.

Con anotaciones de tipos#

def example_function(arg1: int, arg2: int = 4) -> bool:
    """Example function with type hints.

    Args:
        arg1: The first argument.
        arg2: The second argument.

    Returns:
        True if arguments are equal, False otherwise.

    Examples:
        >>> example_function(1, 1)  # True
    """
    return arg1 == arg2

Docstrings de una sola línea#

def example_small_function(arg1: int, arg2: int = 4) -> bool:
    """Example function with a single-line docstring."""
    return arg1 == arg2

Estándares de código 📐#

Estilo de Python#

Calidad del código#

Buenas prácticas#

Marcos de seguridad 🛡️#

Las prácticas de ingeniería de Ultralytics deben alinearse con directrices reconocidas de desarrollo seguro, incluidas OWASP Secure Software Development Lifecycle, OWASP Application Security Verification Standard y OWASP Top 10. Los equipos deben utilizar estas referencias al planificar el diseño seguro, las revisiones, las pruebas y las tareas de corrección.

Gestión de activos 🗂️#

Los activos de ingeniería deben tener un propietario claro y una fuente de información fiable. Esto incluye repositorios, servicios, recursos en la nube, ejecutores de CI/CD, dominios, conjuntos de datos, artefactos de modelos, claves de API, secretos, entornos de despliegue e integraciones de terceros.

Al crear, cambiar o retirar un activo:

• Asigna un propietario y un contacto de mantenimiento.
• Registra el propósito, el entorno, los requisitos de acceso y el estado del ciclo de vida.
• Revisa el acceso y los permisos con privilegios mínimos.
• Mantén los secretos y las credenciales fuera del código, los registros, las capturas de pantalla y la documentación.
• Actualiza los manuales operativos, diagramas, inventarios o la documentación cuando cambien la propiedad o el comportamiento.
• Retira los activos que no utilices para reducir los riesgos de seguridad, costes y mantenimiento.

Revisión de la documentación 📝#

La documentación debe mantenerse alineada con los roles, la propiedad, los flujos de trabajo y las expectativas de seguridad actuales. Cuando cambie un proceso, actualiza la página correspondiente del manual, la documentación pública, el manual operativo o el README en el mismo PR, siempre que sea posible.

Los revisores de la documentación deben comprobar lo siguiente:

• Los nombres de los roles, la propiedad y las vías de escalado están actualizados.
• El texto sobre seguridad, cumplimiento normativo y licencias coincide con la política actual.
• Los enlaces, diagramas, comandos y capturas de pantalla siguen reflejando el producto o el flujo de trabajo.
• Los procesos nuevos o modificados incluyen un propietario claro y una periodicidad de revisión.
• La documentación pública no expone información exclusiva de uso interno, secretos, datos de clientes ni detalles operativos sensibles.

Requisitos de pruebas ✅#

Todos los PR deben incluir una validación acorde con el riesgo del cambio:

pytest tests/

# When coverage is relevant
pytest --cov=ultralytics tests/

Para los cambios en el comportamiento de los modelos, incluye, siempre que sea posible, el conjunto de datos, el modelo, el comando, el hardware y las métricas anteriores y posteriores. Para los cambios en la documentación, genera la documentación localmente e incluye capturas de pantalla o enlaces de vista previa para los cambios de diseño. Consulta CI/Testing para obtener información sobre CI.

Directrices para la revisión de código 👀#

Para colaboradores#

• Mantén los PR centrados en una sola funcionalidad, corrección o actualización de la documentación.
• Explica el problema, la solución, la validación y los riesgos.
• Responde rápidamente a los comentarios.
• Considera la revisión como parte del trabajo, no como un juicio personal.
• Actualiza la descripción del PR si cambia el alcance.

Para revisores#

• Haz la revisión en un plazo de uno o dos días laborables o redirígela rápidamente.
• Comprueba las pruebas y las evidencias de validación del comportamiento nuevo.
• Revisa las actualizaciones de la documentación para detectar cambios visibles para el usuario.
• Evalúa el impacto en el rendimiento, la compatibilidad, la seguridad, la privacidad y la facilidad de mantenimiento.
• Verifica que se superen las comprobaciones de CI pertinentes.
• Proporciona comentarios constructivos y específicos.
• Distingue los problemas que bloquean el cambio de las sugerencias.

Buenas prácticas de Git 🌳#

Commits#

• Usa el presente: «Add feature», no «Added feature».
• Escribe mensajes claros y descriptivos.
• Mantén los commits centrados y lógicos.
• Evita mezclar cambios de formato sin más con cambios de comportamiento.

Ramas#

• Extrae la última versión de main antes de crear ramas.
• Haz rebase o fusiona main antes del envío final cuando la rama se haya desviado.
• Elimina las ramas después de fusionarlas.

Informar de errores 🐞#

Informa de los errores mediante GitHub Issues:

1. Comprueba primero las incidencias existentes
2. Proporciona un ejemplo mínimo reproducible
3. Describe el entorno: sistema operativo, versión de Python, versiones de las bibliotecas y hardware (usa yolo checks para obtener diagnósticos)
4. Explica el comportamiento esperado y el real con los mensajes de error

Para consultar problemas habituales y sus soluciones, consulta nuestra guía de resolución de problemas.

Licencia 📜#

Muchos repositorios de Ultralytics utilizan la licencia AGPL-3.0. Si utilizas código de Ultralytics con licencia AGPL en tu proyecto, es posible que tu proyecto también deba publicarse con AGPL-3.0. Si necesitas utilizar código cerrado o darle un uso comercial, consulta la Licencia Enterprise.

Recursos 📚#

• Guía oficial para colaboradores - Directrices completas para contribuir
• CI/Testing - Detalles de la integración continua
• Documentación - Redacción y mantenimiento de la documentación
• Código de conducta - Normas de la comunidad
• Instrucciones del CLA - Directrices del Acuerdo de licencia de colaborador
• Ejemplo mínimo reproducible - Ejemplos de informes de errores
• Blog de Ultralytics - Últimas novedades y tutoriales
• Eventos de la comunidad - Seminarios web y conferencias