Contribuyendo a los proyectos de código abierto de Ultralytics

Welcome! We're thrilled that you're considering contributing to our Ultralytics open-source projects. Your involvement not only helps enhance the quality of our repositories but also benefits the entire computer vision community. This guide provides clear guidelines and best practices to help you get started.

🤝 Código de conducta

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

🚀 Cómo 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 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. 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 errores o advertencias nuevos.
4. Prueba tus cambios: Antes de enviarlos, prueba tus cambios localmente para confirmar que funcionan como se espera y no causan regresiones. Añade pruebas si vas a introducir una funcionalidad nueva.
5. Confirma tus cambios: Confirma tus cambios con mensajes descriptivos y concisos. Si tus cambios solucionan un problema específico, incluye el número del problema (por ejemplo, Fix #123: Corrected calculation error.).
6. Crea un pull request: Envía un 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 alcance de tus cambios.

📝 Firma del CLA

Antes de que podamos fusionar tu pull request, debes firmar nuestro Acuerdo de Licencia de Colaborador (CLA). Este acuerdo legal garantiza que tus contribuciones tengan la licencia adecuada, lo que permite que el proyecto continúe distribuyéndose bajo la licencia AGPL-3.0.

Tras 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 que diga:

✍️ Docstrings al estilo Google

When adding new functions or classes, include Google-style docstrings for clear, standardized documentation. Always enclose both input and output types in parentheses (e.g., (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

All pull requests must pass the GitHub Actions Continuous Integration (CI) tests before they can be merged. These tests include linting, unit tests, and other checks to ensure that your changes meet the project's quality standards. Review the CI output and address any issues that arise.

✨ 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.
• Haz cambios más pequeños y enfocados: Céntrate en modificaciones específicas en lugar de cambios a gran escala.
• Simplifica cuando sea posible: Busca oportunidades para simplificar el código o eliminar partes innecesarias.
• Considera la compatibilidad: Antes de hacer cambios, piensa si podrían romper el código existente que utiliza Ultralytics.
• Usa un formato consistente: Herramientas como Ruff Formatter pueden ayudarte a mantener la consistencia estilística.
• Añade pruebas apropiadas: Incluye pruebas para las nuevas funcionalidades y asegúrate de que funcionan como se espera.

👀 Revisión de pull requests

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

• Comprueba si hay 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 documentación se actualice 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 están pasando.
• Proporciona comentarios constructivos: Ofrece comentarios específicos y claros sobre cualquier problema o inquietud.
• Reconoce el esfuerzo: Reconoce el trabajo del autor para mantener un ambiente de colaboración positivo.

🐞 Informe de errores

Valoramos mucho los informes de errores, ya que nos ayudan a mejorar la calidad y 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 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 constante. Esto es crucial para una depuración eficiente.
• Describe el entorno: Especifica tu sistema operativo, versión de Python, versiones relevantes de las librerías (por ejemplo, torch, ultralytics) y el hardware (CPU/GPU).
• Explica el comportamiento esperado frente al real: Indica claramente qué esperabas que sucediera y qué ocurrió realmente. Incluye cualquier mensaje de error o rastro (tracebacks).

📜 Licencia

Ultralytics utiliza la GNU Affero General Public License v3.0 (AGPL-3.0) para sus repositorios. Esta licencia promueve la apertura, la transparencia y la mejora colaborativa en el desarrollo de software. Garantiza que todos los usuarios tengan la libertad de usar, modificar y compartir el software, fomentando una sólida comunidad 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.

🌍 Cómo hacer que tu proyecto YOLO sea de código abierto bajo AGPL-3.0

¿Usas modelos o código de Ultralytics YOLO en tu proyecto? La licencia AGPL-3.0 requiere que toda tu obra derivada también se publique bajo licencia AGPL-3.0. Esto garantiza que las modificaciones y los proyectos más grandes construidos sobre bases de código abierto permanezcan abiertos.

Por qué es importante cumplir con la AGPL-3.0

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

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

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 repositorio de Ultralytics YOLO si lo usas como base principal.
   • Usa la plantilla de Ultralytics: Empieza con el repositorio de plantillas de Ultralytics para 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 licencia AGPL-3.0.
   • Añade un aviso en la parte superior de cada archivo fuente indicando 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 sistema más grande completo que incorpora 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.
     • Pesos del modelo si han sido modificados o ajustados (fine-tuned).
     • 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 librería de terceros que hayas modificado.
     • Datos de entrenamiento si son necesarios para ejecutar/reentrenar y pueden ser redistribuidos.

4. Documenta claramente:

   • Actualiza tu README.md para indicar que el proyecto está bajo licencia AGPL-3.0.
   • Incluye instrucciones claras sobre cómo configurar, construir y ejecutar tu proyecto desde el código fuente.
   • Atribuye a Ultralytics YOLO adecuadamente, incluyendo 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 de 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, apoyando el ecosistema de código abierto que permite herramientas tan potentes como Ultralytics YOLO.

Conclusión

Thank you for your interest in contributing to Ultralytics open-source YOLO projects. Your participation is essential in shaping the future of our software and building a vibrant community of innovation and collaboration. Whether you're enhancing code, reporting bugs, or suggesting new features, your contributions are invaluable.

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

Preguntas frecuentes

¿Por qué debería contribuir a los repositorios de código abierto de Ultralytics YOLO?

Contribuir a los repositorios de código abierto de Ultralytics YOLO mejora el software, haciéndolo más robusto y rico en funciones para toda la comunidad. Las contribuciones pueden incluir mejoras de código, correcciones de errores, mejoras de documentación e implementaciones de nuevas funciones. Además, contribuir te permite colaborar con otros desarrolladores y expertos cualificados en el campo, mejorando tus propias habilidades y reputación. Para obtener detalles sobre cómo empezar, consulta la sección Cómo contribuir mediante Pull Requests.

¿Cómo firmo el Acuerdo de Licencia de Colaborador (CLA) para Ultralytics YOLO?

Para firmar el Acuerdo de Licencia de Colaborador (CLA), sigue las instrucciones proporcionadas por el bot del CLA después de enviar tu pull request. Este proceso garantiza que tus contribuciones tengan la licencia adecuada bajo la licencia AGPL-3.0, manteniendo la integridad legal del proyecto de código abierto. Añade un comentario en tu pull request que diga:

Para obtener más información, consulta la sección Firma del CLA.

¿Qué son los docstrings al estilo Google y por qué son necesarios para las contribuciones a Ultralytics YOLO?

Los docstrings al estilo Google proporcionan una documentación clara y concisa para funciones y clases, mejorando la legibilidad y mantenibilidad del código. Estos docstrings describen el propósito de la función, los argumentos y los valores de retorno con reglas de formato específicas. Al contribuir a Ultralytics YOLO, seguir los docstrings al estilo Google asegura que tus aportaciones estén bien documentadas y sean fáciles de entender. Para ver ejemplos y directrices, visita la sección Docstrings al estilo Google.

¿Cómo puedo asegurarme de que mis cambios superen las pruebas de CI de GitHub Actions?

Antes de que tu pull request pueda ser fusionado, debe superar todas las pruebas de Integración Continua (CI) de GitHub Actions. Estas pruebas incluyen linting, pruebas unitarias y otras verificaciones para garantizar que el código cumpla con los estándares de calidad del proyecto. Revisa el resultado de la CI y soluciona cualquier problema. Para obtener información detallada sobre el proceso de CI y consejos de solución de problemas, consulta la sección GitHub Actions CI Tests.

¿Cómo informo de un error en los repositorios de YOLO de Ultralytics?

Para informar de un error, proporciona un Minimum Reproducible Example claro y conciso junto con tu informe de error. Esto ayuda a los desarrolladores a identificar y solucionar el problema rápidamente. Asegúrate de que tu ejemplo sea mínimo pero suficiente para replicar el problema. Para conocer los pasos detallados sobre cómo informar errores, consulta la sección Reporting Bugs.

¿Qué significa la licencia AGPL-3.0 si utilizo YOLO de Ultralytics en mi propio proyecto?

Si utilizas código o modelos de YOLO de Ultralytics (con licencia bajo AGPL-3.0) en tu proyecto, la licencia AGPL-3.0 exige que todo tu proyecto (la obra derivada) también esté bajo la licencia AGPL-3.0 y que su código fuente completo esté disponible públicamente. Esto garantiza que la naturaleza de código abierto del software se preserve en sus derivados. Si no puedes cumplir con estos requisitos, necesitas obtener una Enterprise License. Consulta la sección Open-Sourcing Your Project para obtener más detalles.