Contribuir a los proyectos de código abierto de Ultralytics#

¡Te damos la bienvenida! Nos alegra mucho que te plantees contribuir a nuestros proyectos de Ultralytics de código abierto. Tu participación no solo ayuda a mejorar la calidad de nuestros repositorios, sino que también beneficia a toda la comunidad de visión artificial. Esta guía ofrece directrices claras y buenas prácticas para ayudarte a empezar.

Código de conducta#

Para garantizar un entorno acogedor e inclusivo para todo el mundo, todas las personas colaboradoras deben cumplir nuestro Código de conducta. El respeto, la amabilidad y la profesionalidad son pilares fundamentales de nuestra comunidad.

Contribuir mediante solicitudes de incorporación de cambios#

Agradecemos enormemente las contribuciones en forma de solicitudes de incorporación de cambios (PR). Para que el proceso de revisión sea lo más sencillo posible, sigue estos pasos:

1. Haz un fork del repositorio: Empieza por hacer un fork del repositorio de Ultralytics correspondiente (por ejemplo, ultralytics/ultralytics) en tu cuenta de GitHub.
2. Crea una rama: Crea una nueva rama en el repositorio del que has hecho un fork, con un nombre claro y descriptivo que refleje tus cambios (por ejemplo, fix-issue-123, add-feature-xyz).
3. Realiza los cambios: Implementa tus mejoras o correcciones. Asegúrate de que el código siga las directrices de estilo del proyecto y no introduzca errores ni advertencias nuevos.
4. Prueba los cambios: Antes de enviarlos, prueba los cambios localmente para confirmar que funcionan como se espera y no provocan regresiones. Añade pruebas si incorporas nuevas funciones.
5. Confirma los cambios: Confirma los cambios con mensajes concisos y descriptivos. Si tus cambios resuelven una incidencia concreta, incluye el número de la incidencia (por ejemplo, Fix #123: Corrected calculation error.).
6. Crea una solicitud de incorporación de cambios: Envía una solicitud de incorporación de cambios desde tu rama a la rama main del repositorio original de Ultralytics. Incluye un título claro y una descripción detallada que explique el propósito y el alcance de tus cambios.

Instalación para desarrollo#

Clona tu fork (o el repositorio principal) e instálalo en modo editable (-e) para que Python ejecute tus archivos locales y detecte cada cambio sin tener que reinstalar:

git clone https://github.com/YOUR_USERNAME/ultralytics.git
cd ultralytics
pip install -e .

Para que otro proyecto dependa de un fork en lugar del paquete de PyPI, indica en pip o en requirements.txt la rama del fork:

git+https://github.com/YOUR_USERNAME/ultralytics.git@my-custom-branch

Cambios en la documentación#

El código fuente de la documentación se encuentra en docs/en/. Desde la raíz del repositorio, instala las dependencias de desarrollo y ejecuta la validación estricta completa antes de abrir una PR:

uv pip install -e ".[dev]"
python docs/build_docs.py

La validación prepara referencias generadas, macros y páginas de comparación antes de ejecutar zensical build --strict. Para obtener una vista previa en directo más rápida de las páginas que no usan macros, ejecuta zensical serve.

Firma del CLA#

Antes de poder integrar tu solicitud de incorporación de cambios, debes firmar nuestro Acuerdo de licencia de colaborador (CLA). Este acuerdo legal garantiza que tus contribuciones cuenten con la licencia adecuada y permite que el proyecto siga distribuyéndose bajo la licencia AGPL-3.0.

Después de enviar tu solicitud de incorporación de cambios, el bot del CLA te guiará durante el proceso de firma. Para firmar el CLA, solo tienes que añadir un comentario a tu PR que diga:

I have read the CLA Document and I sign the CLA

Docstrings al estilo de Google#

Al añadir funciones o clases nuevas, incluye docstrings al estilo de Google para que la documentación sea clara y uniforme. Incluye siempre entre paréntesis tanto las types de entrada como las de salida (por ejemplo, (bool), (np.ndarray)).

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

Pruebas de CI de GitHub Actions#

Todas las solicitudes de incorporación de cambios deben superar las pruebas de GitHub Actions de integración continua (CI) antes de poder integrarse. Estas pruebas incluyen análisis estático, pruebas unitarias y otras comprobaciones para garantizar que tus cambios cumplen los estándares de calidad del proyecto. Revisa los resultados de CI y resuelve cualquier problema que aparezca.

Buenas prácticas para contribuir con código#

Al contribuir con código a los proyectos de Ultralytics, ten en cuenta estas buenas prácticas:

• Evita duplicar código: Reutiliza el código existente siempre que sea posible y reduce al mínimo los argumentos innecesarios.
• Haz cambios pequeños y específicos: Céntrate en modificaciones concretas en lugar de cambios a gran escala.
• Simplifica siempre que sea posible: Busca oportunidades para simplificar el código o eliminar partes innecesarias.
• Ten en cuenta la compatibilidad: Antes de hacer cambios, considera si podrían romper el código existente que utiliza Ultralytics.
• Usa un formato coherente: Herramientas como Ruff Formatter pueden ayudarte a mantener la coherencia estilística.
• Añade pruebas adecuadas: Incluye pruebas para las nuevas funciones y comprueba que funcionan como se espera.

Revisión de solicitudes de incorporación de cambios#

Revisar solicitudes de incorporación de cambios es otra forma valiosa de contribuir. Al revisar PR:

• Comprueba que haya pruebas unitarias: Verifica que la PR incluya pruebas para las funciones o los cambios nuevos.
• Revisa las actualizaciones de la documentación: Asegúrate de que la documentación esté actualizada para reflejar los cambios.
• Evalúa el impacto en el rendimiento: Considera cómo podrían afectar los cambios al rendimiento.
• Verifica las pruebas de CI: Confirma que todas las pruebas de integración continua se hayan superado.
• Ofrece comentarios constructivos: señala problemas o inquietudes concretos y con claridad.
• Reconoce el esfuerzo: valora el trabajo del autor para mantener un ambiente de colaboración positivo.

Informar de errores#

Valoramos mucho los informes de errores, ya que nos ayudan a mejorar la calidad y la fiabilidad de nuestros proyectos. Al informar de un error mediante GitHub Issues:

• Comprueba las incidencias existentes: busca primero para ver si alguien ya ha informado del error.
• Proporciona un ejemplo mínimo reproducible: crea un fragmento de código pequeño y autónomo que reproduzca el problema de forma sistemática. Esto es fundamental para depurar el código con eficacia.
• Describe el entorno: indica tu sistema operativo, la versión de Python, las versiones pertinentes de las bibliotecas (p. ej., torch, ultralytics) y el hardware (CPU/GPU).
• Explica el comportamiento esperado y el real: indica claramente qué esperabas que ocurriera y qué ha ocurrido en realidad. Incluye cualquier mensaje de error o traceback.

Licencia#

Ultralytics utiliza la Licencia Pública General Affero de GNU versión 3.0 (AGPL-3.0) para sus repositorios. Esta licencia fomenta la apertura, la transparencia y la mejora colaborativa en el desarrollo de software. Garantiza que todos los usuarios tengan libertad para utilizar, modificar y compartir el software, y fomenta una comunidad sólida de colaboración e innovación.

Animamos a todos los colaboradores a familiarizarse con los términos de la licencia AGPL-3.0 para contribuir de forma eficaz y ética a la comunidad de código abierto de Ultralytics.

Publicar tu proyecto YOLO como código abierto bajo AGPL-3.0#

¿Utilizas modelos o código de Ultralytics YOLO en tu proyecto? La licencia AGPL-3.0 exige que toda tu obra derivada también se publique como código abierto bajo AGPL-3.0. Así se garantiza que las modificaciones y los proyectos de mayor envergadura basados en código abierto sigan siendo abiertos.

Por qué es importante cumplir la AGPL-3.0#

• Mantiene el software abierto: garantiza que la comunidad se beneficie de las mejoras y las obras derivadas.
• Requisito legal: el uso de código con licencia AGPL-3.0 obliga a tu proyecto a cumplir sus términos.
• Fomenta la colaboración: anima a compartir y a actuar con transparencia.

Si prefieres no publicar tu proyecto como código abierto, plantéate obtener una licencia Enterprise.

Cómo cumplir la AGPL-3.0#

Cumplirla significa poner a disposición del público el código fuente completo correspondiente de tu proyecto bajo la licencia AGPL-3.0.

1. Elige por dónde empezar:

   • Haz un fork de Ultralytics YOLO: haz directamente un fork del repositorio de Ultralytics YOLO si vas a crear algo basado estrechamente en él.
   • Usa la plantilla de Ultralytics: empieza con el repositorio de plantillas de Ultralytics para disponer de una estructura modular y limpia que integre YOLO.

2. Aplica una licencia a tu proyecto:

   • Añade un archivo LICENSE que contenga el texto completo de la licencia AGPL-3.0.
   • Añade un aviso en la parte superior de cada archivo de código fuente para indicar la licencia.

3. Publica tu código fuente:

   • Haz que el código fuente completo de tu proyecto esté disponible públicamente (p. ej., en GitHub). Esto incluye:
     • La aplicación o el sistema completo de mayor envergadura que incorpore el modelo o el código YOLO.
     • Cualquier modificación del código original de Ultralytics YOLO.
     • Scripts de entrenamiento, validación e inferencia.
     • Pesos del modelo si se han modificado o ajustado.
     • Archivos de configuración, configuraciones del entorno (requirements.txt, Dockerfiles).
     • Código de backend y frontend si forma parte de una aplicación web.
     • Cualquier biblioteca de terceros que hayas modificado.
     • Datos de entrenamiento si son necesarios para ejecutar o volver a entrenar el modelo y se pueden redistribuir.

4. Documenta con claridad:

   • Actualiza tu README.md para indicar que el proyecto está sujeto a la licencia AGPL-3.0.
   • Incluye instrucciones claras para configurar, compilar y ejecutar tu proyecto a partir del código fuente.
   • Atribuye correctamente Ultralytics YOLO e incluye un enlace al repositorio original. Ejemplo:

     This project utilizes code from [Ultralytics YOLO](https://github.com/ultralytics/ultralytics), licensed under AGPL-3.0.

Ejemplo de estructura del repositorio#

Consulta el repositorio de plantillas de Ultralytics para ver un ejemplo práctico de estructura:

my-yolo-project/
│
├── LICENSE               # Full AGPL-3.0 license text
├── README.md             # Project description, setup, usage, license info & attribution
├── pyproject.toml        # Dependencies (or requirements.txt)
├── scripts/              # Training/inference scripts
│   └── train.py
├── src/                  # Your project's source code
│   ├── __init__.py
│   ├── data_loader.py
│   └── model_wrapper.py  # Code interacting with YOLO
├── tests/                # Unit/integration tests
├── configs/              # YAML/JSON config files
├── docker/               # Dockerfiles, if used
│   └── Dockerfile
└── .github/              # GitHub specific files (e.g., workflows for CI)
    └── workflows/
        └── ci.yml

Al seguir estas pautas, garantizas el cumplimiento de AGPL-3.0 y contribuyes al ecosistema de código abierto que hace posibles herramientas potentes como Ultralytics YOLO.

Conclusión#

Gracias por tu interés en contribuir a los proyectos YOLO de código abierto de Ultralytics. Tu participación es esencial para dar forma al futuro de nuestro software y crear una comunidad dinámica de innovación y colaboración. Tus contribuciones son muy valiosas, ya sea para mejorar código, informar de errores o proponer nuevas funciones.

Nos hace mucha ilusión ver cómo tus ideas se hacen realidad y agradecemos tu compromiso con el avance de la tecnología de detección de objetos. Sigamos creciendo e innovando juntos en esta apasionante trayectoria de código abierto.

Preguntas frecuentes#