Flujo de trabajo de desarrollo 💻

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

El flujo es ligero a propósito: mantén los cambios enfocados, facilita la revisión, ejecuta las comprobaciones adecuadas y deja contexto suficiente para que tu equipo entienda más adelante por qué se decidió así.

Código de conducta 🤝

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

Cadencia de colaboración 🛰️

• Anchor Days (mar/mié/jue): 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.
• Lun/vie: Prioriza el trabajo profundo, las actualizaciones por escrito, la preparación de PR y la revisión asíncrona. Lleva los bloqueos críticos al siguiente Anchor Day cuando se necesite alineación síncrona.
• Standups y revisiones: Limita los standups a 15 minutos. Programa las revisiones de diseño y arquitectura en Anchor Days siempre que sea posible.
• Decisiones documentadas: Captura las decisiones importantes en descripciones de PR, issues, docs o runbooks para que el contexto no se pierda en chats.

Alcance y responsabilidad 🧭

Este flujo se aplica al trabajo de ingeniería de Ultralytics en producto, Ultralytics Platform, YOLO, infraestructura, documentación, automatización y sistemas sensibles a 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 un responsable claro:

• Autor: Implementa el cambio, mantiene el PR al día y aporta evidencias de validación.
• Revisor: Confirma corrección, mantenibilidad, riesgos e impacto en la documentación.
• Responsable de dominio: Revisa los cambios que afectan a un área especializada como comportamiento de modelos, infraestructura, seguridad, privacidad, licencias o flujos de cara al cliente.
• Responsable de triage: Asigna issues, incidentes, reportes de vulnerabilidades y trabajo de mantenimiento al responsable adecuado.

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

1. Haz fork o sincroniza el repositorio

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

Los empleados con permisos de escritura deben sincronizar main antes de crear ramas:

# 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 pruebas, Validación de modelos, Flujos de CI

5. Haz commit de tus cambios

Haz commit con mensajes concisos y descriptivos:

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

6. Crea la pull request

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

8. Atiende los comentarios de la revisión

Responde a los comentarios de los revisores, sube actualizaciones y mantén la descripción del PR al día si cambia el alcance. Resuelve todo el feedback bloqueante antes de pedir una nueva revisión.

Docstrings al estilo Google 📝

Las funciones y clases públicas deberían usar docstrings al estilo Google cuando el repositorio así lo espere. Mantén los docstrings precisos, concisos y útiles para los 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

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 varios valores, documenta cada valor de retorno por separado en lugar de esconder los detalles importantes en 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 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 guías reconocidas de desarrollo seguro, incluyendo el Ciclo de vida de desarrollo seguro de OWASP, el Estándar de verificación de seguridad de aplicaciones de OWASP y el OWASP Top 10. Los equipos deben usar estas referencias al planificar el diseño, la revisión, las pruebas y la remediación seguros.

Gestión de activos 🗂️

Los activos de ingeniería deben tener un responsable claro y una fuente de verdad fiable. Esto incluye repositorios, servicios, recursos cloud, runners de CI/CD, dominios, datasets, artefactos de modelos, claves de API, secretos, entornos de despliegue e integraciones de terceros.

Al crear, modificar o retirar un activo:

• Asigna un responsable y un contacto de mantenimiento.
• Registra el propósito, el entorno, los requisitos de acceso y el estado del ciclo de vida.
• Revisa los accesos y los permisos de mínimo privilegio.
• Mantén los secretos y credenciales fuera del código, los logs, las capturas y la documentación.
• Actualiza runbooks, diagramas, inventarios o documentación cuando cambie la propiedad o el comportamiento.
• Retira los activos no utilizados para reducir riesgos de seguridad, costes y mantenimiento.

Revisión de la documentación 📝

La documentación debe permanecer alineada con los roles, responsabilidades, flujos y expectativas de seguridad actuales. Cuando cambie un proceso, actualiza la página correspondiente del manual, la documentación pública, el runbook o el README en el mismo PR cuando sea factible.

Los revisores de documentación deben comprobar:

• Los nombres de roles, responsabilidades y caminos de escalado están al día.
• El lenguaje sobre seguridad, cumplimiento y licencias coincide con la política actual.
• Los enlaces, diagramas, comandos y capturas siguen reflejando el producto o el flujo.
• Los procesos nuevos o modificados incluyen un responsable claro y una cadencia de revisión.
• La documentación pública no expone información solo interna, secretos, datos de clientes ni detalles operativos sensibles.

Requisitos de pruebas ✅

Todos los PR deben incluir validaciones acordes con el riesgo del cambio:

pytest tests/

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

Para cambios en el comportamiento de modelos, incluye el dataset, el modelo, el comando, el hardware y las métricas antes/después siempre que sea factible. Para cambios de documentación, construye los docs en local e incluye capturas o enlaces de previsualización para los cambios de maquetación. Consulta CI/Testing para los detalles de CI.

Pautas de revisión de código 👀

Para los colaboradores

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

Para los revisores

• Revisa en uno o dos días laborables o redirige rápido.
• Comprueba pruebas y evidencias de validación para el nuevo comportamiento.
• Revisa las actualizaciones de documentación para los cambios visibles al usuario.
• Evalúa el impacto en rendimiento, compatibilidad, seguridad, privacidad y mantenibilidad.
• Verifica que las comprobaciones de CI relevantes pasan.
• Da feedback constructivo y específico.
• Diferencia los problemas bloqueantes de las sugerencias.

Buenas prácticas con Git 🌳

Commits

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

Ramas

• Haz pull del último main antes de crear ramas.
• Haz rebase o merge de main antes del envío final cuando la rama se haya quedado atrás.
• Borra las ramas tras hacer merge.

Reportar errores 🐞

Reporta los errores a través de GitHub Issues:

1. Comprueba primero las issues existentes
2. Aporta un Ejemplo mínimo reproducible
3. Describe el entorno: SO, versión de Python, versiones de las librerías, hardware (usa yolo checks para diagnósticos)
4. Explica el comportamiento esperado frente al real con los mensajes de error

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

Licencia 📜

Muchos repositorios de Ultralytics usan la licencia AGPL-3.0. Si usas código de Ultralytics con licencia AGPL en tu proyecto, puede que tu proyecto también deba liberarse como open source bajo AGPL-3.0. Si necesitas un uso de código cerrado o comercial, revisa la Enterprise License.

Recursos 📚

• Guía oficial de contribución - Pautas completas de contribución
• CI/Testing - Detalles de integración continua
• Documentación - Escribir y mantener documentación
• Código de conducta - Estándares de la comunidad
• Instrucciones del CLA - Guía sobre el Contributor License Agreement
• Ejemplo mínimo reproducible - Ejemplos de reportes de errores
• Blog de Ultralytics - Últimas novedades y tutoriales
• Eventos de la comunidad - Webinars y conferencias