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

¡Bienvenido! Nos encanta que estés considerando contribuir a nuestros proyectos de código abierto de Ultralytics. 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 por computador. Esta guía proporciona directrices claras y mejores prácticas para ayudarte a empezar.

🤝 Código de conducta#

Para garantizar un entorno acogedor e inclusivo para todo el mundo, todos los colaboradores deben cumplir nuestro Code of Conduct. El respeto, la amabilidad y la profesionalidad son el núcleo de nuestra comunidad.

🚀 Contribuir mediante pull requests#

Agradecemos enormemente las contribuciones en forma de pull requests (PRs). Para que el proceso de revisión sea lo más fluido posible, sigue estos pasos:

1. Haz un fork del repositorio: Empieza haciendo 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 tu repositorio bifurcado con un nombre claro y descriptivo que refleje tus cambios (por ejemplo, fix-issue-123, add-feature-xyz).
3. Realiza tus cambios: Implementa tus mejoras o correcciones. Asegúrate de que tu código cumpla con las directrices de estilo del proyecto y no introduzca nuevos errores ni advertencias.
4. Prueba tus cambios: Antes de enviarlos, prueba tus cambios localmente para confirmar que funcionan como se espera y no provocan regresiones. Añade tests si vas a introducir nueva funcionalidad.
5. Haz un commit de tus cambios: Haz un commit de tus cambios con mensajes concisos y descriptivos. Si tus cambios solucionan un problema específico, incluye el número de la incidencia (por ejemplo, Fix #123: Corrected calculation error.).
6. Crea una pull request: Envía una pull request 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.

📚 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 un PR:

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

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

📝 Firma del CLA#

Antes de que podamos fusionar tu pull request, debes firmar nuestro Contributor License Agreement (CLA). Este acuerdo legal garantiza que tus contribuciones tienen la licencia adecuada, lo que permite que el proyecto siga distribuyéndose bajo la AGPL-3.0 license.

Después de enviar tu pull request, el bot del CLA te guiará durante el proceso de firma. Para firmar el CLA, simplemente añade un comentario en tu PR indicando:

I have read the CLA Document and I sign the CLA

✍️ Docstrings al estilo Google#

Al añadir nuevas funciones o clases, incluye Google-style docstrings para obtener una documentación clara y estandarizada. Encierra siempre las entradas y salidas 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 pull requests deben superar las pruebas de Continuous Integration (CI) de GitHub Actions antes de poder fusionarse. Estas pruebas incluyen el análisis de código (linting), pruebas unitarias y otras comprobaciones para garantizar que tus cambios cumplan con los estándares de calidad del proyecto. Revisa la salida de CI y soluciona cualquier problema que surja.

✨ Mejores prácticas para contribuciones de código#

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

• Evita la duplicación de código: Reutiliza el código existente siempre que sea posible y minimiza los argumentos innecesarios.
• Realiza cambios pequeños y específicos: Céntrate en modificaciones concretas en lugar de en cambios a gran escala.
• Simplifica siempre que puedas: Busca oportunidades para simplificar el código o eliminar partes innecesarias.
• Considera la compatibilidad: Antes de realizar cambios, valora 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 de estilo.
• Añade los tests adecuados: Incluye tests para las nuevas características para garantizar que funcionan como se espera.

👀 Revisión de pull requests#

Revisar pull requests es otra forma valiosa de contribuir. Al revisar PRs:

• Comprueba las pruebas unitarias: Verifica que el PR incluya pruebas para nuevas funciones o cambios.
• Revisa las actualizaciones de la documentación: Asegúrate de que la documentation está actualizada para reflejar los cambios.
• Evalúa el impacto en el rendimiento: Considera cómo los cambios pueden afectar al performance.
• Verifica los tests de la CI: Confirma que todas las Continuous Integration tests pasan correctamente.
• Proporciona comentarios constructivos: Ofrece comentarios específicos y claros sobre cualquier problema o duda.
• Reconoce el esfuerzo: Reconoce el trabajo del autor para mantener un ambiente de colaboración positivo.

🐞 Informar de errores#

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

• Comprueba los problemas existentes: Busca primero para ver si el error ya ha sido reportado.
• Proporciona un Minimum Reproducible Example: Crea un fragmento de código pequeño y autónomo que reproduzca el problema de forma sistemática. Esto es fundamental para una depuración eficiente.
• Describe el entorno: Especifica tu sistema operativo, la versión de Python, las versiones de las librerías relevantes (por ejemplo, torch, ultralytics) y el hardware (CPU/GPU).
• Explica el comportamiento esperado frente al real: Indica claramente qué esperabas que ocurriera y qué ocurrió realmente. Incluye cualquier mensaje de error o rastro (traceback).

📜 Licencia#

Ultralytics utiliza la GNU Affero General Public License v3.0 (AGPL-3.0) para sus repositorios. Esta licencia fomenta la openness, la transparency y el collaborative improvement en el desarrollo de software. Garantiza que todos los usuarios tengan la libertad de usar, modificar y compartir el software, promoviendo una sólida comunidad de colaboración e innovación.

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

🌍 Publicar tu proyecto YOLO bajo AGPL-3.0#

¿Vas a usar modelos o código de Ultralytics YOLO en tu proyecto? La AGPL-3.0 license exige que toda tu obra derivada también sea de código abierto bajo la licencia AGPL-3.0. Esto garantiza que las modificaciones y los proyectos más grandes construidos sobre cimientos de código abierto sigan siendo abiertos.

Por qué es importante el cumplimiento de la AGPL-3.0#

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

Si prefieres no hacer que tu proyecto sea de código abierto, valora la posibilidad de obtener una Enterprise License.

Cómo cumplir con la AGPL-3.0#

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

1. Elige tu punto de partida:

   • Haz un fork de Ultralytics YOLO: Haz un fork directo del Ultralytics YOLO repository si vas a construir tu proyecto muy cerca de él.
   • Usa la plantilla de Ultralytics: Empieza con el Ultralytics template repository para obtener una configuración limpia y modular que integre YOLO.

2. Licencia tu proyecto:

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

3. Publica tu código fuente:

   • Haz que el código fuente de todo tu proyecto sea accesible públicamente (por ejemplo, en GitHub). Esto incluye:
     • La aplicación o sistema completo más grande que incorpore el modelo o código YOLO.
     • Cualquier modificación realizada en el código original de Ultralytics YOLO.
     • Scripts para entrenamiento, validación e inferencia.
     • Model weights si se han modificado o ajustado (fine-tuned).
     • Configuration files, configuraciones del entorno (requirements.txt, Dockerfiles).
     • Código de backend y frontend si forma parte de una web application.
     • Cualquier third-party libraries que hayas modificado.
     • Training data si es necesario para ejecutar/reentrenar y es redistribuible.

4. Documenta claramente:

   • Actualiza tu README.md para indicar que el proyecto cuenta con la licencia AGPL-3.0.
   • Incluye instrucciones claras sobre cómo configurar, compilar y ejecutar tu proyecto a partir del código fuente.
   • Atribuye la autoría a Ultralytics YOLO de forma adecuada, enlazando al original repository. Ejemplo:

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

Ejemplo de estructura de repositorio#

Consulta el Ultralytics Template Repository para ver una estructura de ejemplo práctica:

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, apoyando el 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 fundamental para dar forma al futuro de nuestro software y construir una comunidad dinámica de innovación y colaboración. Ya sea que estés mejorando código, informando de errores o sugiriendo nuevas características, tus contribuciones son de un valor incalculable.

Nos emociona ver cómo cobran vida tus ideas y agradecemos tu compromiso con el avance de la tecnología de object detection. Sigamos creciendo e innovando juntos en este apasionante viaje del código abierto.

FAQ#