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 tarde.

Código de conducta 🤝

Todos los colaboradores deben seguir el Código de Conducta. Se espera respeto, claridad y profesionalidad en incidencias, PRs, revisiones, discusiones internas y espacios públicos de la comunidad. Para ver 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: Favorece el trabajo profundo, las actualizaciones escritas, la preparación de PRs y la revisión asíncrona. Traslada los bloqueos críticos al siguiente día de anclaje cuando sea necesario 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, incidencias, documentación 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, la mantenibilidad, el riesgo y el impacto en la documentación.
• Propietario del dominio: 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 de cara al cliente.
• Propietario de triaje: Asigna las incidencias, incidentes, informes de vulnerabilidad y trabajos de mantenimiento entrantes al propietario correcto.

Proceso de Pull Request 🔄

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

    style A fill:#e1f5ff
    style J fill:#d4edda
    style G fill:#fff3cd

Bifurca (fork) o sincroniza el repositorio

Los colaboradores externos deben hacer fork del repositorio de Ultralytics relevante, 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

Crea una rama de funcionalidad (feature branch)

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

git checkout -b fix-issue-123

Realiza tus cambios

Prueba tus cambios

pytest tests/

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

Confirma (commit) tus cambios

Haz commit con mensajes concisos y descriptivos:

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

Crea un Pull Request

Envía la PR desde tu rama a main:

Firma el CLA

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

El bot del CLA te guiará a través del proceso. Para más detalles sobre licencias, consulta nuestra guía de contribución.

Responde a los comentarios de revisión

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

Docstrings al estilo Google 📝

Las funciones y clases públicas deben utilizar docstrings al 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 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

Retornos múltiples

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 genérica de tupla.

✅ 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

Buenas prácticas

Marcos de seguridad 🛡️

Las prácticas de ingeniería de Ultralytics deben alinearse con la orientación 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 remediació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, runners 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 privilegio mínimo.
• Mantén los secretos y las credenciales fuera del código, los registros, las capturas de pantalla y la documentación.
• Actualiza los runbooks, diagramas, inventarios o documentación cuando la propiedad o el comportamiento cambien.
• Retira los activos no utilizados para reducir el riesgo de seguridad, coste y mantenimiento.

Revisión de documentación 📝

La documentación debe permanecer alineada con los roles, la propiedad, los flujos de trabajo y las expectativas de seguridad actuales. Cuando un proceso cambie, actualiza la página del manual relevante, los documentos públicos, el runbook o el README en la misma PR cuando sea práctico.

Los revisores de documentación deben comprobar:

• Que los nombres de los roles, la propiedad y las vías de escalada estén actualizados.
• Que el lenguaje sobre seguridad, cumplimiento y licencias coincida con la política actual.
• Que los enlaces, diagramas, comandos y capturas de pantalla sigan reflejando el producto o 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 solo interna, secretos, datos de clientes o detalles operativos sensibles.

Requisitos de pruebas ✅

Todas las PRs deben incluir una validación que coincida 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, modelo, comando, hardware y métricas antes/después cuando sea práctico. Para cambios en la documentación, compila los documentos localmente e incluye capturas de pantalla o enlaces de vista previa para cambios de diseño. Consulta CI/Testing para detalles sobre CI.

Pautas de revisión de código 👀

Para colaboradores

• Mantén las PRs enfocadas 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 puntualmente a los comentarios.
• Trata la revisión como parte del trabajo, no como un juicio personal.
• Actualiza la descripción de la PR si el alcance cambia.

Para revisores

• Revisa en un plazo de uno a dos días hábiles 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 rendimiento, la compatibilidad, la seguridad, la privacidad y el impacto en la mantenibilidad.
• Verifica que las comprobaciones de CI relevantes se aprueben.
• Proporciona comentarios constructivos y específicos.
• Distingue los problemas bloqueantes de las sugerencias.

Buenas prácticas de Git 🌳

Commits

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

Ramas

• Extrae el último main antes de crear ramas.
• Rebase o fusiona main antes de la entrega 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 Minimum Reproducible Example
3. Describe el entorno: SO, versión de Python, versiones de bibliotecas, 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 - Pautas 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 - Orientación sobre el Contributor License Agreement
• Minimum Reproducible Example - Ejemplos de informes de errores
• Blog de Ultralytics - Últimas actualizaciones y tutoriales
• Eventos de la comunidad - Webinars y conferencias