Link to this sectionFlujo 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, incluyendo YOLO y repositorios relacionados.

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

Link to this sectionCó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 los requisitos de colaboración póblica, consulta la Guía oficial de colaboración.

Link to this sectionCadencia de colaboración 🛖#

• Días de anclaje (mar/mié/jue): Utiliza 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: Favorece 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 las reuniones diarias 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 decisiones importantes en descripciones de PR, incidencias, documentos o manuales de operación para que el contexto no desaparezca en el chat.

Link to this sectionAlcance y propiedad 🧭#

Este flujo de trabajo se aplica al trabajo de ingeniería de Ultralytics en productos, Plataforma Ultralytics, 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 tarea de trabajo debe tener un responsable 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.
• Responsable 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.
• Responsable de triaje: Asigna las incidencias entrantes, incidentes, informes de vulnerabilidad y trabajos de mantenimiento al responsable adecuado.

Link to this sectionProceso 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

Link to this sectionBifurca o sincroniza el repositorio#

Los colaboradores externos deben bifurcar el 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

Link to this sectionCrea una rama de funcionalidad#

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

git checkout -b fix-issue-123

Link to this sectionRealiza tus cambios#

Link to this sectionPrueba tus cambios#

pytest tests/

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

Link to this sectionConfirma tus cambios#

Confirma con mensajes concisos y descriptivos:

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

Link to this sectionCrea un Pull Request#

Envía la PR desde tu rama a main:

Link to this sectionFirma el CLA#

Tras 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 colaboración.

Link to this sectionAtiende los comentarios de revisión#

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

Link to this sectionDocstrings al estilo Google 📝#

Las funciones y clases póblicas deben usar docstrings al estilo Google donde el repositorio lo requiera. Mantén las docstrings precisas, concisas y ótiles para futuros responsables del mantenimiento.

Link to this sectionFunció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

Link to this sectionRetornos 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

Link to this sectionRetornos 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 devuelva 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.

Link to this sectionCon sugerencias de tipo#

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

Link to this sectionDocstrings de una línea#

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

Link to this sectionEstándares de código 📐#

Link to this sectionEstilo de Python#

Link to this sectionCalidad del código#

Link to this sectionMejores prácticas#

Link to this sectionMarcos 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 usar estas referencias al planificar el diseño, la revisión, las pruebas y el trabajo de remediación seguro.

Link to this sectionGestió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, registros, capturas de pantalla y 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, costes y mantenimiento.

Link to this sectionRevisión de documentación 📝#

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

Los revisores de documentación deben comprobar:

• Que los nombres de 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 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.

Link to this sectionRequisitos de pruebas ✅#

Todos los 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 de antes/después cuando sea práctico. Para cambios en la documentación, compila la documentación localmente e incluye capturas de pantalla o enlaces de vista previa para cambios de diseño. Consulta CI/Testing para detalles sobre CI.

Link to this sectionPautas de revisión de código 👀#

Link to this sectionPara colaboradores#

• Mantén los PRs enfocados 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 del PR si el alcance cambia.

Link to this sectionPara 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 el mantenimiento.
• Verifica que las comprobaciones de CI relevantes pasen.
• Proporciona comentarios constructivos y específicos.
• Distingue los problemas bloqueantes de las sugerencias.

Link to this sectionMejores prácticas de Git 🌳#

Link to this sectionCommits#

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

Link to this sectionRamas#

• Descarga la última versión de main antes de crear ramas.
• Haz un rebase o fusión de main antes de la entrega final cuando la rama se haya desviado.
• Elimina las ramas después de la fusión.

Link to this sectionReportar errores 🐞#

Reporta errores mediante GitHub Issues:

1. Comprueba los issues existentes primero.
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 resolución de problemas.

Link to this sectionLicencia 📜#

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 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 Enterprise License.

Link to this sectionRecursos 📚#

• Official Contributing Guide - Pautas completas de contribución.
• CI/Testing - Detalles de integración continua.
• Documentation - Escritura y mantenimiento de documentación.
• Code of Conduct - Estándares de la comunidad.
• CLA Instructions - Guía del Acuerdo de Licencia de Colaborador.
• Minimum Reproducible Example - Ejemplos de reportes de errores.
• Ultralytics Blog - Últimas actualizaciones y tutoriales.
• Community Events - Seminarios web y conferencias.