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 los repositorios relacionados.

El flujo de trabajo es intencionadamente sencillo: mantén los cambios centrados, facilita la revisión, ejecuta las comprobaciones adecuadas y deja suficiente contexto para que el equipo pueda entender la decisión más adelante.

Código de conducta 🤝#

Todos los colaboradores deben respetar 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. Consulta la Guía oficial de contribución para conocer los requisitos de las contribuciones públicas.

Ritmo de colaboración 🛰️#

• Días clave (martes/miércoles/jueves): Aprovecha estos días para las revisiones de código, los debates de diseño, las sesiones de depuración y las decisiones que se beneficien de la colaboración en tiempo real.
• Lunes/viernes: Prioriza el trabajo en profundidad, las actualizaciones por escrito, la preparación de PR y las revisiones asíncronas. Traslada los bloqueos críticos al siguiente día clave cuando sea necesario coordinarse en tiempo real.
• Reuniones diarias y revisiones: Limita las reuniones diarias a 15 minutos. Cuando sea posible, programa las revisiones de diseño y arquitectura para los días clave.
• Registros de decisiones: Documenta las decisiones importantes en las descripciones de PR, las incidencias, la documentación o los manuales operativos para que el contexto no se pierda 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 a la seguridad. Cada repositorio puede añadir requisitos más estrictos, pero no debe rebajar las expectativas básicas de esta página.

Cada tarea debe tener una persona responsable claramente definida:

• Autor: Implementa el cambio, mantiene actualizado el PR y aporta pruebas de validación.
• Revisor: Comprueba la corrección, la facilidad de mantenimiento, los riesgos 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 de cara al cliente.
• Responsable de triaje: Asigna las incidencias recibidas, los incidentes, los informes de vulnerabilidades y las tareas de mantenimiento a la persona adecuada.

Proceso de solicitud de cambios 🔄#

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 para la funcionalidad#

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

git checkout -b fix-issue-123

3. Haz los cambios#

4. Prueba los cambios#

pytest tests/

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

5. Confirma los cambios#

Confirma los cambios con mensajes concisos y descriptivos:

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

6. Crea una solicitud de cambios#

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á 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 así lo requiera. Procura que los docstrings sean precisos, concisos 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

Varios 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 por separado en lugar de ocultar detalles importantes en una descripción genérica de una 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 ajustarse a directrices reconocidas de desarrollo seguro, como Ciclo de vida de desarrollo de software seguro de OWASP, Estándar de verificación de seguridad de aplicaciones de OWASP y OWASP Top 10. Los equipos deben usar 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 responsable 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, 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 con los mínimos privilegios necesarios.
• No incluyas secretos ni credenciales en el código, los registros, las capturas de pantalla ni la documentación.
• Actualiza los procedimientos operativos, los diagramas, los inventarios o la documentación cuando cambien la responsabilidad o el comportamiento.
• Retira los activos que no se usen para reducir los riesgos de seguridad, costes y mantenimiento.

Revisión de la documentación 📝#

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

Al revisar la documentación, comprueba lo siguiente:

• Los nombres de los roles, las responsabilidades y las vías de escalado están actualizados.
• El lenguaje sobre seguridad, cumplimiento y licencias se ajusta a 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 responsable claro y una periodicidad de revisión.
• La documentación pública no expone información solo para uso interno, secretos, datos de clientes ni detalles operativos sensibles.

Requisitos de pruebas ✅#

Todas las PR deben incluir una validación acorde con el riesgo del cambio:

pytest tests/

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

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

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

Para quienes contribuyen#

• Centra las PR 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 cuanto antes a los comentarios.
• Considera la revisión parte del trabajo, no un juicio personal.
• Actualiza la descripción de la PR si cambia su alcance.

Para quienes revisan#

• Revisa en uno o dos días laborables o redirige la solicitud rápidamente.
• Comprueba las pruebas y las evidencias de validación de los nuevos comportamientos.
• Revisa las actualizaciones de la documentación para detectar cambios visibles para los usuarios.
• Evalúa el impacto en el rendimiento, la compatibilidad, la seguridad, la privacidad y la mantenibilidad.
• Comprueba que se superen las verificaciones de CI pertinentes.
• Ofrece comentarios constructivos y concretos.
• Distingue los problemas que bloquean la aprobación de las sugerencias.

Buenas prácticas de Git 🌳#

Commits#

• Usa el presente: «Añadir funcionalidad», no «Funcionalidad añadida».
• Redacta mensajes claros y descriptivos.
• Mantén los commits centrados y coherentes.
• Evita mezclar cambios de formato sin impacto funcional con cambios de comportamiento.

Ramas#

• Actualiza main antes de crear ramas.
• Rebasa o fusiona main antes del envío definitivo si la rama se ha desfasado.
• 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 el diagnóstico)
4. Explica el comportamiento esperado y el real con los mensajes de error

Para consultar problemas habituales y sus soluciones, visita 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, es posible que también tengas que publicar tu proyecto con la licencia AGPL-3.0. Si necesitas un uso comercial o con código cerrado, consulta la Licencia Enterprise.

Recursos 📚#

• Guía oficial para contribuir - Directrices completas para contribuir
• CI/Testing - Información sobre 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 contribución
• Ejemplo mínimo reproducible - Ejemplos para informar de errores
• Blog de Ultralytics - Últimas novedades y tutoriales
• Eventos de la comunidad - Seminarios web y conferencias