Ir al contenido

Flujo de trabajo de desarrollo 💻

Esta guía cubre el proceso de desarrollo para contribuir a los proyectos de Ultralytics, incluyendo YOLO11 y los repositorios relacionados.

Código de conducta 🤝

Todos los colaboradores deben adherirse a nuestro Código de Conducta. El respeto, la amabilidad y la profesionalidad son el corazón de nuestra comunidad. Para obtener directrices detalladas sobre la contribución, consulta la Guía oficial de contribución.

Proceso de solicitud de extracción (Pull Request) 🔄

1. Bifurca el repositorio

Haga un fork del repositorio de Ultralytics correspondiente (por ejemplo, ultralytics/ultralytics) en su cuenta de GitHub.

# Clone your fork
git clone https://github.com/YOUR_USERNAME/ultralytics.git
cd ultralytics

2. Crea una rama de función

Cree una rama con un nombre claro y descriptivo:

git checkout -b fix-issue-123

Convenciones para nombrar ramas:

  • fix-issue-123 para correcciones de errores
  • add-feature-xyz para nuevas funciones
  • update-docs-training para la documentación

3. Realiza tus cambios

  • Siga las guías de estilo del proyecto
  • Evite introducir nuevos errores o advertencias
  • Mantenga los cambios enfocados y mínimos

4. Prueba tus cambios

Pruebe localmente antes de enviar:

pytest tests/

Añade pruebas para la nueva funcionalidad para evitar regresiones. Obtén más información sobre los requisitos de las pruebas, la validación de modelos y nuestros flujos de trabajo de CI.

5. Confirma tus cambios

Commit con mensajes concisos y descriptivos:

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

Incluye el número de incidencia al abordar problemas específicos.

6. Crea una solicitud de extracción (Pull Request)

Enviar PR desde tu rama a main:

  • Título claro que describa el cambio
  • Descripción detallada del propósito y el alcance
  • Enlaza incidencias relacionadas
  • Incluye capturas de pantalla para los cambios en la interfaz de usuario

7. Firma el CLA

Antes de fusionar, debes firmar nuestro Acuerdo de Licencia de Colaborador (CLA). Esto garantiza que las contribuciones estén debidamente licenciadas bajo la licencia AGPL-3.0.

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

I have read the CLA Document and I sign the CLA

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

8. Aborda los comentarios de la revisión

Responde a los comentarios del revisor y envía las actualizaciones.

Docstrings al estilo de Google 📝

Todas las funciones y clases requieren docstrings al estilo de Google con tipos entre paréntesis.

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

Devoluciones 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

Devoluciones 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: Documentar cada valor de retorno por separado, no como una 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

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

  • Ancho de línea: 120 caracteres como máximo
  • Docstrings: Estilo Google con tipos entre paréntesis
  • Importaciones: Use pathlib en lugar de os
  • Type hints: Utilizar donde sea beneficioso para la claridad
  • Funciones: Mantenerlas cortas y enfocadas (idealmente, menos de 50 líneas)

Calidad del código

  • No debe haber importaciones o variables sin usar
  • Nombres consistentes (lowercase_with_underscores)
  • Nombres de variables claros (evitar letras sueltas, excepto para contadores de bucles)
  • f-strings para el formateo
  • Comentarios solo para lógica compleja

Buenas prácticas

  • Evitar la duplicación: Reutilizar el código existente
  • Cambios más pequeños: Modificaciones enfocadas en lugar de cambios a gran escala
  • Simplifica: Busca oportunidades de simplificación
  • Compatibilidad: Evitar romper el código existente
  • Formato consistente: Utilizar Ruff Formatter
  • Añada pruebas: Incluya pruebas para las nuevas funcionalidades

Requisitos de Pruebas ✅

Todas las PR deben pasar las pruebas de CI:

# Run tests locally
pytest tests/

# With coverage
pytest --cov=ultralytics tests/

Ver CI/Testing para más detalles sobre CI.

Directrices para la revisión del código 👀

Para colaboradores

  • Mantener las PR enfocadas en una sola característica/corrección
  • Responder con prontitud a los comentarios
  • No tomarse los comentarios de forma personal
  • Actualizar la descripción de la PR si cambia el alcance

Para revisores

  • Revisar en 1-2 días hábiles
  • Comprobar las pruebas unitarias para las nuevas características
  • Revisar las actualizaciones de la documentación
  • Evaluar el impacto en el rendimiento
  • Verificar que las pruebas de CI se superen
  • Proporcionar comentarios constructivos y específicos
  • Reconocer el esfuerzo del autor

Buenas prácticas de Git 🌳

Confirmaciones

  • Tiempo presente: "Añadir función" no "Función añadida"
  • Mensajes claros y descriptivos
  • Commits lógicos y enfocados

Ramas

  • Extraer lo último main antes de crear ramas
  • Rebasar en main antes de la entrega final
  • Eliminar las ramas después de la fusión

Informar de errores 🐞

Informar de los errores a través de GitHub Issues:

  1. Comprobar primero los problemas existentes
  2. Proporcionar un Ejemplo Mínimo Reproducible
  3. Describe el entorno: SO, versión de python, versiones de la biblioteca, hardware (utiliza yolo checks para el diagnóstico)
  4. Explicar el comportamiento esperado frente al comportamiento real con mensajes de error

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

Licencia 📜

Ultralytics utiliza AGPL-3.0. Si utilizas código de Ultralytics en tu proyecto, todo tu proyecto debe ser de código abierto bajo AGPL-3.0. Si prefieres no utilizar código abierto, obtén una Licencia Empresarial.

Recursos 📚



📅 Creado hace 1 mes ✏️ Actualizado hace 9 días
glenn-jocher