Contribución a proyectos de código abierto de Ultralytics

¡Bienvenido! Nos emociona que estés considerando contribuir a nuestros proyectos 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 mejores prácticas para ayudarte a empezar.

Ver: Cómo contribuir al repositorio de Ultralytics | Modelos, conjuntos de datos y documentación de Ultralytics 🚀

🤝 Código de Conducta

Para garantizar un entorno acogedor e inclusivo para todos, todos los contribuyentes deben adherirse a nuestro Código de Conducta. El respeto, la amabilidad y el profesionalismo son el corazón de nuestra comunidad.

🚀 Contribución mediante "Pull Requests"

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

1. Haz un fork del repositorio: Comienza haciendo un fork del repositorio de Ultralytics correspondiente (p. ej., ultralytics/ultralytics) a tu cuenta de GitHub.
2. Cree una rama: Crea una nueva rama en tu repositorio bifurcado con un nombre claro y descriptivo que refleje tus cambios (p. ej., fix-issue-123, add-feature-xyz).
3. Realice sus cambios: Implemente sus mejoras o correcciones. Asegúrese de que su código cumpla con las pautas de estilo del proyecto y no introduzca nuevos errores o advertencias.
4. Pruebe sus cambios: Antes de enviar, pruebe sus cambios localmente para confirmar que funcionan como se espera y no causan regresiones. Agregue pruebas si está introduciendo nuevas funcionalidades.
5. Confirme sus cambios: Confirme sus cambios con mensajes de confirmación concisos y descriptivos. Si sus cambios abordan un problema específico, incluya el número del problema (p. ej., Fix #123: Corrected calculation error.).
6. Cree una solicitud de extracción: Envíe una solicitud de extracción desde su rama al main rama del repositorio original de Ultralytics. Proporcione un título claro y una descripción detallada que explique el propósito y el alcance de sus cambios.

📝 Firma de CLA

Antes de que podamos fusionar tu "pull request", debes firmar nuestro Acuerdo de Licencia de Colaborador (CLA). Este acuerdo legal asegura que tus contribuciones estén debidamente licenciadas, permitiendo que el proyecto continúe distribuyéndose bajo la licencia AGPL-3.0.

Después de enviar tu solicitud de extracción (pull request), el bot de CLA te guiará a través del 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

✍️ Cadenas de documentación al estilo de Google

Al agregar nuevas funciones o clases, incluya Docstrings al estilo de Google para una documentación clara y estandarizada. Siempre incluya tanto la entrada como la salida types entre paréntesis (p. ej., (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

def example_function(arg1, arg2=4):
    """
    Example function demonstrating Google-style docstrings.

    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

def example_function(arg1, arg2=4):
    """
    Example function demonstrating Google-style docstrings.

    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

Returns:
   (np.ndarray): Predicted masks with shape HxWxN.
   (list): Confidence scores for each instance.

Returns:
   (tuple): Tuple containing:
       - (np.ndarray): Predicted masks with shape HxWxN.
       - (list): Confidence scores for each instance.

def example_function(arg1: int, arg2: int = 4) -> bool:
    """
    Example function demonstrating Google-style docstrings.

    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

def example_small_function(arg1: int, arg2: int = 4) -> bool:
    """Example function with a single-line docstring."""
    return arg1 == arg2

✅ Pruebas de CI de GitHub Actions

Todas las solicitudes de extracción deben pasar las pruebas de GitHub Actions de Integración Continua (CI) antes de que puedan fusionarse. Estas pruebas incluyen el análisis de código, pruebas unitarias y otras verificaciones 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 las contribuciones de código

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

• Evite la duplicación de código: Reutilice el código existente siempre que sea posible y minimice los argumentos innecesarios.
• Realice cambios más pequeños y enfocados: Concéntrese en modificaciones específicas en lugar de cambios a gran escala.
• Simplifique cuando sea posible: Busque oportunidades para simplificar el código o eliminar partes innecesarias.
• Considere la compatibilidad: Antes de realizar cambios, considere si podrían romper el código existente que utiliza Ultralytics.
• Utilice un formato coherente: Herramientas como Ruff Formatter pueden ayudar a mantener la coherencia estilística.
• Añada pruebas adecuadas: Incluya pruebas para las nuevas funciones a fin de garantizar que funcionen según lo previsto.

👀 Revisión de "Pull Requests"

Revisar las "pull requests" es otra forma valiosa de contribuir. Al revisar los PR:

• Comprobar pruebas unitarias: Verifique que la PR incluya pruebas para nuevas funcionalidades o cambios.
• Revisar las actualizaciones de la documentación: Asegúrese de que la documentación se actualice para reflejar los cambios.
• Evaluar el impacto en el rendimiento: Considere cómo los cambios podrían afectar el rendimiento.
• Verificar pruebas de CI: Confirmar que todas las pruebas de Integración Continua están pasando.
• Proporcione comentarios constructivos: Ofrezca comentarios específicos y claros sobre cualquier problema o inquietud.
• Reconocer el esfuerzo: Reconozca el trabajo del autor para mantener un ambiente colaborativo positivo.

🐞 Reporte de errores

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

• Comprobar problemas existentes: Busque primero para ver si el error ya ha sido reportado.
• Proporcione un Ejemplo Mínimo Reproducible: Cree un fragmento de código pequeño y autocontenido que reproduzca el problema de forma consistente. Esto es crucial para una depuración eficiente.
• Describa el entorno: Especifique su sistema operativo, la versión de python, las versiones de las bibliotecas relevantes (p. ej., torch, ultralytics), y el hardware (CPU/GPU).
• Explique el comportamiento esperado frente al real: Indique claramente lo que esperaba que sucediera y lo que realmente ocurrió. Incluya cualquier mensaje de error o traza.

📜 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ódigo Abierto de tu proyecto YOLO bajo AGPL-3.0

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

¿Por qué es importante el cumplimiento de la licencia AGPL-3.0?

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

Si prefiere no utilizar código abierto en su proyecto, considere la posibilidad de obtener una Licencia Enterprise.

Cómo cumplir con AGPL-3.0

Cumplir significa hacer que el código fuente correspondiente completo de su proyecto esté disponible públicamente bajo la licencia AGPL-3.0.

1. Elija su punto de partida:

   • Haz un fork de Ultralytics YOLO: Haz un fork directamente del repositorio de Ultralytics YOLO si vas a construir sobre él de manera estrecha.
   • Utilice la plantilla de Ultralytics: Comience con el repositorio de plantillas de Ultralytics para una configuración limpia y modular que integre YOLO.

2. Licencia de su proyecto:

   • Añada un LICENSE archivo que contiene el texto completo del Licencia AGPL-3.0.
   • Añada un aviso en la parte superior de cada archivo fuente que indique la licencia.

3. Publica tu código fuente:

   • Haz tu código fuente de todo el proyecto de acceso público (por ejemplo, en GitHub). Esto incluye:
     • La aplicación o sistema completo más grande que incorpora el modelo o código YOLO.
     • Cualquier modificación realizada al código original de Ultralytics YOLO.
     • Scripts para entrenamiento, validación e inferencia.
     • Pesos del modelo si se modifican o se ajustan.
     • Archivos de configuración, configuraciones de entorno (requirements.txt, Dockerfiles).
     • Código de backend y frontend si forma parte de una aplicación web.
     • Cualquier biblioteca de terceros que haya modificado.
     • Datos de entrenamiento si es necesario para ejecutar/volver a entrenar y redistribuible.

4. Documente Claramente:

   • Actualiza tu README.md para indicar que el proyecto está licenciado bajo AGPL-3.0.
   • Incluye instrucciones claras sobre cómo configurar, construir y ejecutar tu proyecto desde el código fuente.
   • Atribuya Ultralytics YOLO apropiadamente, enlazando de nuevo a 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

Consulte 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, garantiza el cumplimiento de AGPL-3.0, apoyando el ecosistema de código abierto que permite herramientas potentes como Ultralytics YOLO.

🎉 Conclusión

Gracias por su interés en contribuir a los proyectos YOLO de Ultralytics de código abierto. Su participación es esencial para dar forma al futuro de nuestro software y construir una comunidad vibrante de innovación y colaboración. Ya sea que esté mejorando el código, informando errores o sugiriendo nuevas funciones, sus contribuciones son invaluables.

Nos entusiasma ver sus ideas hacerse realidad y apreciamos su compromiso para avanzar en la tecnología de detección de objetos. Juntos, sigamos creciendo e innovando en este emocionante viaje de código abierto. ¡Feliz codificación! 🚀🌟

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 le permite colaborar con otros desarrolladores y expertos cualificados en el campo, mejorando sus propias habilidades y reputación. Para obtener más información sobre cómo empezar, consulte la sección Contribución mediante "Pull Requests".

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

Para firmar el Acuerdo de Licencia del Contribuyente (CLA), sigue las instrucciones proporcionadas por el bot de CLA después de enviar tu solicitud de extracción. Este proceso asegura que tus contribuciones estén debidamente licenciadas bajo la licencia AGPL-3.0, manteniendo la integridad legal del proyecto de código abierto. Agrega un comentario en tu solicitud de extracción que diga:

I have read the CLA Document and I sign the CLA

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

¿Qué son las cadenas de documentación al estilo de Google y por qué son necesarias para las contribuciones de Ultralytics YOLO?

Las cadenas de documentación al estilo de Google proporcionan una documentación clara y concisa para funciones y clases, mejorando la legibilidad y el mantenimiento del código. Estas cadenas de documentación describen el propósito, los argumentos y los valores de retorno de la función con reglas de formato específicas. Al contribuir a Ultralytics YOLO, seguir las cadenas de documentación al estilo de Google asegura que tus adiciones estén bien documentadas y sean fácilmente comprensibles. Para ejemplos y directrices, visita la sección Cadenas de Documentación al Estilo de Google.

¿Cómo puedo asegurar que mis cambios pasen las pruebas de CI de GitHub Actions?

Antes de que tu "pull request" pueda ser fusionada, debe pasar todas las pruebas de Integración Continua (CI) de GitHub Actions. Estas pruebas incluyen "linting", pruebas unitarias y otras comprobaciones para asegurar que el código cumple con los estándares de calidad del proyecto. Revisa la salida de CI y corrige cualquier problema. Para obtener información detallada sobre el proceso de CI y consejos para la resolución de problemas, consulta la sección Pruebas de CI de GitHub Actions.

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

Para informar de un error, proporciona un Ejemplo Mínimo Reproducible 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 reproducir el problema. Para obtener pasos más detallados sobre cómo informar de errores, consulta la sección Informar de errores.

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

Si utiliza código o modelos de Ultralytics YOLO (con licencia AGPL-3.0) en su proyecto, la licencia AGPL-3.0 exige que todo su proyecto (el trabajo derivado) también se licencie bajo AGPL-3.0 y que su código fuente completo se ponga a disposición del público. Esto garantiza que la naturaleza de código abierto del software se conserve en todos sus derivados. Si no puede cumplir estos requisitos, debe obtener una Licencia Enterprise. Consulte la sección Código abierto de su proyecto para obtener más información.

📅 Creado hace 1 año ✏️ Actualizado hace 2 meses

Comentarios