Flujo de trabajo de desarrollo 💻#

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

El flujo de trabajo es intencionadamente ligero: mantén los cambios enfocados, facilita la revisión, ejecuta las comprobaciones correctas 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 issues, PRs, revisiones, discusiones internas y espacios públicos de la comunidad. Para conocer los requisitos de contribución pública, consulta la Guía de contribución oficial.

Cadencia de colaboración 🛰️#

• Días de anclaje (mar/mié/jue): Utiliza estos días para revisiones de código, discusiones de diseño, sesiones de depuración y decisiones que se beneficien de la colaboración síncrona.
• lun/vie: Prioriza el trabajo profundo, las actualizaciones por escrito, la preparación de PRs y la revisión asíncrona. Traslada los bloqueos críticos al siguiente día de anclaje cuando sea necesaria una alineación síncrona.
• Standups y revisiones: Limita los standups a 15 minutos. Programa las revisiones de diseño y arquitectura en los días de anclaje siempre que sea posible.
• Registros de decisiones: Captura las decisiones importantes en las descripciones de las PRs, issues, docs o runbooks para que el contexto no desaparezca en el chat.

Alcance y propiedad 🧭#

Este flujo de trabajo se aplica al trabajo de ingeniería de Ultralytics en productos, Ultralytics Platform, YOLO, infraestructura, documentación, automatización y sistemas sensibles a la seguridad. Los repositorios individuales pueden añadir requisitos más estrictos, pero no deben debilitar las expectativas básicas de esta página.

Cada elemento de trabajo debe tener un propietario claro:

• Autor: Implementa el cambio, mantiene la PR actualizada y proporciona pruebas de validación.
• Revisor: Confirma la corrección, mantenibilidad, riesgo e impacto en la documentación.
• Propietario del dominio: Revisa los cambios que afectan a un área especializada como el comportamiento del modelo, infraestructura, seguridad, privacidad, licencias o flujos de trabajo orientados al cliente.
• Propietario de triaje: Asigna las issues entrantes, incidentes, informes de vulnerabilidad y trabajos de mantenimiento al propietario correcto.

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 fork del repositorio de Ultralytics relevante, como ultralytics/ultralytics, a 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. Haz tus cambios#

4. Prueba tus cambios#

pytest tests/

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

5. Confirma (commit) tus cambios#

Haz commit con mensajes concisos y descriptivos:

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

6. Crea un Pull Request#

Envía la 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á por el proceso. Para más detalles sobre licencias, consulta nuestra guía de contribución.

8. Atiende los comentarios de revisión#

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

Docstrings estilo Google 📝#

Las funciones y clases públicas deben utilizar docstrings estilo Google donde el repositorio lo requiera. Mantén los docstrings precisos, concisos y útiles para futuros mantenedores.

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

Retornos nombrados#

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 retornos#

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 múltiples valores, documenta cada valor de retorno por separado en lugar de ocultar detalles importantes dentro de una descripción de tupla genérica.

✅ Bien:

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

❌ Mal:

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

Con sugerencias de tipo (type hints)#

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 Python#

Calidad del código#

Mejores prácticas#

Marcos de seguridad 🛡️#

Las prácticas de ingeniería de Ultralytics deben alinearse con la guía de desarrollo seguro reconocida, incluyendo 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, la revisión, las pruebas y el trabajo 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, datasets, 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 de mínimo privilegio.
• Mantén los secretos y las credenciales fuera del código, los registros, las capturas de pantalla y la documentación.
• Actualiza los manuales de ejecución (runbooks), diagramas, inventarios o documentación cuando cambie la propiedad o el comportamiento.
• Retira los activos no utilizados para reducir el riesgo de seguridad, coste y mantenimiento.

Revisión de 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 de ejecución o el archivo README en el mismo PR, cuando sea posible.

Los revisores de documentación deben comprobar:

• Que los nombres de los roles, la propiedad y las rutas de escalada estén actualizados.
• Que el lenguaje de seguridad, cumplimiento y licencias coincida con la política actual.
• Que los enlaces, diagramas, comandos y capturas de pantalla sigan reflejando el producto o el flujo de trabajo.
• Que los procesos nuevos o modificados incluyan un propietario claro y una cadencia de revisión.
• Que la documentación pública no exponga información interna, secretos, datos de clientes o detalles operativos sensibles.

Requisitos de pruebas ✅#

Todos los PRs deben incluir una validación que se corresponda con el riesgo del cambio:

pytest tests/

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

Para cambios en el comportamiento del modelo, incluye el dataset, el modelo, el comando, el hardware y las métricas de antes/después cuando sea posible. Para 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 más detalles sobre CI.

Pautas de revisión de código 👀#

Para colaboradores#

• Mantén los PRs centrados en una característica, corrección o actualización de documentación.
• Explica el problema, la solución, la validación y los riesgos.
• Responde con prontitud a los comentarios.
• Trata la revisión como parte del trabajo, no como un juicio personal.
• Actualiza la descripción del PR si cambia el alcance.

Para revisores#

• Revisa en un plazo de uno a dos días laborables o redirige rápidamente.
• Comprueba las pruebas y la evidencia de validación para el nuevo comportamiento.
• Revisa las actualizaciones de documentación para cambios visibles al usuario.
• Evalúa el impacto en rendimiento, compatibilidad, seguridad, privacidad y mantenibilidad.
• Verifica que las comprobaciones de CI relevantes se aprueban.
• Proporciona comentarios constructivos y específicos.
• Distingue los problemas bloqueantes de las sugerencias.

Mejores prácticas de Git 🌳#

Commits#

• Usa el tiempo presente: "Add feature" no "Added feature".
• Escribe mensajes claros y descriptivos.
• Mantén los commits centrados y lógicos.
• Evita mezclar cambios de solo formato con cambios de comportamiento.

Ramas#

• Extrae la main más reciente antes de crear ramas.
• Rebase o fusiona main antes de la presentación final cuando la rama se haya desviado.
• Elimina las ramas después de la fusión.

Informar de errores 🐞#

Informa de errores a través de GitHub Issues:

1. Comprueba primero los problemas existentes
2. Proporciona un Ejemplo Mínimo Reproducible
3. Describe el entorno: SO, versión de Python, versiones de biblioteca, hardware (usa yolo checks para diagnósticos)
4. Explica el comportamiento esperado frente al real con mensajes de error

Para problemas comunes y soluciones, consulta nuestra guía de solució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 ser de código abierto bajo AGPL-3.0. Si necesitas un uso comercial o de código cerrado, revisa la Licencia Enterprise.

Recursos 📚#

• Guía oficial de contribución - Directrices completas de contribución
• CI/Testing - Detalles de integración continua
• Documentación - Escritura y mantenimiento de documentos
• Código de conducta - Estándares de la comunidad
• Instrucciones CLA - Guía del Acuerdo de Licencia de Contribuyente
• Ejemplo Mínimo Reproducible - Ejemplos de informes de errores
• Blog de Ultralytics - Últimas actualizaciones y tutoriales
• Eventos de la comunidad - Webinars y conferencias