Contribuir a proyectos de código abierto de Ultralytics#

¡Te damos la bienvenida! Nos entusiasma que estés considerando 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 proporciona directrices claras y buenas prácticas para ayudarte a empezar.

Código de conducta#

Para garantizar un entorno acogedor e inclusivo para todos, todos los colaboradores deben cumplir nuestro Código de conducta. El respeto, la amabilidad y el profesionalismo son fundamentales en nuestra comunidad.

Contribuir mediante PR#

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 fluido posible, sigue estos pasos:

1. Bifurca el repositorio: Empieza bifurcando el repositorio de Ultralytics correspondiente (por ejemplo, ultralytics/ultralytics) en tu cuenta de GitHub.
2. Crea una rama: Crea una rama nueva en tu repositorio bifurcado con un nombre claro y descriptivo que refleje tus cambios (por ejemplo, fix-issue-123, add-feature-xyz).
3. Haz los cambios: Implementa tus mejoras o correcciones. Asegúrate de que tu código cumpla las directrices de estilo del proyecto y no introduzca errores ni advertencias nuevos.
4. Prueba los cambios: Antes de enviar los cambios, pruébalos localmente para confirmar que funcionan según lo esperado y no provocan regresiones. Añade pruebas si introduces una funcionalidad nueva.
5. Confirma los cambios: Confirma tus cambios con mensajes de confirmación concisos y descriptivos. Si tus cambios resuelven un problema específico, incluye su número (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. Proporciona 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 bifurcación (o el repositorio principal) e instálala en modo editable (-e) para que Python ejecute tus archivos locales y detecte cada cambio sin necesidad de reinstalar:

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

Para hacer que otro proyecto dependa de una bifurcación en lugar del paquete de PyPI, apunta pip o requirements.txt a la rama de la bifurcación:

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 las referencias generadas, las macros y las 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 fusionar tu solicitud de incorporación de cambios, debes firmar nuestro Acuerdo de licencia de contribuidor (CLA). Este acuerdo legal garantiza que tus contribuciones cuentan con la licencia adecuada, lo que 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 en tu PR que indique:

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 proporcionar una documentación clara y estandarizada. Incluye siempre tanto la entrada como la salida types entre paréntesis (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 con 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 fusionarse. Estas pruebas incluyen análisis de estilo, pruebas unitarias y otras comprobaciones para garantizar que tus cambios cumplen los estándares de calidad del proyecto. Revisa la salida de CI y resuelve cualquier problema que surja.

Buenas prácticas para contribuciones de 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 minimiza los argumentos innecesarios.
• Haz cambios pequeños y específicos: Céntrate en modificaciones concretas en lugar de cambios a gran escala.
• Simplifica cuando 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 usa Ultralytics.
• Usa un formato coherente: Herramientas como Ruff Formatter pueden ayudarte a mantener la coherencia del estilo.
• Añade pruebas adecuadas: Incluye pruebas para las funcionalidades nuevas y asegúrate de que funcionan según lo esperado.

Revisión de PR#

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

• Comprueba las pruebas unitarias: Verifica que la PR incluya pruebas para las funcionalidades 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 superen correctamente.
• Proporciona comentarios constructivos: Ofrece comentarios específicos y claros sobre cualquier problema o inquietud.
• Reconoce el esfuerzo: Valora el trabajo del autor para mantener un ambiente colaborativo positivo.

Reportar errores#

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

• Comprueba los problemas existentes: Busca primero para comprobar si el error ya se ha informado.
• Proporciona un ejemplo mínimo reproducible: Crea un fragmento de código pequeño y autónomo que reproduzca el problema de forma coherente. Esto es fundamental para depurar eficazmente.
• Describe el entorno: Especifica tu sistema operativo, la versión de Python, las versiones relevantes de las bibliotecas (por ejemplo, torch, ultralytics) y el hardware (CPU/GPU).
• Explica el comportamiento esperado y el real: Indica claramente qué esperabas que ocurriera y qué ocurrió realmente. Incluye cualquier mensaje de error o rastreo de pila.

Licencia#

Ultralytics utiliza la Licencia Pública General Affero de GNU v3.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 usar, modificar y compartir el software, fomentando una comunidad sólida de colaboración e innovación.

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

Hacer tu proyecto de YOLO de código abierto bajo AGPL-3.0#

¿Usas modelos o código YOLO de Ultralytics 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. Esto garantiza que las modificaciones y los proyectos más grandes creados sobre bases de código abierto sigan siendo abiertos.

Por qué es importante cumplir la AGPL-3.0#

• Mantiene el software abierto: Garantiza que las mejoras y las obras derivadas beneficien a la comunidad.
• Requisito legal: El uso de código con licencia AGPL-3.0 vincula tu proyecto a sus condiciones.
• Fomenta la colaboración: Anima a compartir y a mantener la transparencia.

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

Cómo cumplir la AGPL-3.0#

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

1. Elige tu punto de partida:

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

2. Licencia 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 que indique la licencia.

3. Publica tu código fuente:

   • Haz que el código fuente completo de tu proyecto sea accesible públicamente (por ejemplo, en GitHub). Esto incluye:
     • La aplicación o el sistema completo de mayor tamaño que incorpore el modelo o el código YOLO.
     • Cualquier modificación realizada en el código YOLO original de Ultralytics.
     • Scripts para entrenamiento, validación e inferencia.
     • Pesos del modelo si se han modificado o ajustado.
     • Archivos de configuración y configuraciones del entorno (requirements.txt, Dockerfiles).
     • Código de backend y frontend si forman 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 se distribuye bajo la licencia AGPL-3.0.
   • Incluye instrucciones claras sobre cómo configurar, compilar y ejecutar tu proyecto a partir del código fuente.
   • Atribuye correctamente Ultralytics YOLO y enlaza 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 directrices, garantizas el cumplimiento de la AGPL-3.0 y contribuyes al ecosistema de código abierto que permite crear herramientas potentes como Ultralytics YOLO.

Conclusión#

Gracias por tu interés en contribuir a los proyectos YOLO de Ultralytics de código abierto. Tu participación es esencial para dar forma al futuro de nuestro software y construir una comunidad dinámica de innovación y colaboración. Ya sea que mejores código, informes de errores o sugieras funcionalidades nuevas, tus contribuciones son inestimables.

Nos entusiasma ver cómo tus ideas cobran vida y agradecemos tu compromiso con el avance de la tecnología de detección de objetos. Juntos, sigamos creciendo e innovando en este apasionante recorrido de código abierto.

Preguntas frecuentes#