Contribuir al código

Conceptos básicos de contribución

  • Contribuir puede ser tan simple como hacer preguntas, informar problemas, participar en debates, sugerir nuevas funciones, etc. ¡Todo esto es valioso! Hay muchas maneras de contribuir. También aprecio mucho cuando compartes las cosas creativas que has hecho usando qteasy (tanto el código como las imágenes de la trama). Y, por supuesto, escribir código para qteasy también es una excelente manera de contribuir. Gracias.

  • Se aplican todas las pautas habituales/típicas de contribución de código abierto (consulte, por ejemplo, Guía de contribución de código abierto). Por lo tanto, aquí, en esta página, mencionaré solo algunos elementos sobre los que puedo ser particular en qteasy.

Informar problemas

  • Proporcione una descripción clara del problema y la información del entorno en el que está trabajando. Preferiblemente, utilice plantilla de informe de error e incluya las siguientes secciones en su descripción:

    • Sus expectativas: describa lo que está tratando de lograr mientras encontró el problema.

    • Su método: proporcione el código que crea que habría dado los resultados esperados

    • El resultado: describe lo que realmente obtienes con Tu método, proporciona mensajes de error

    • Su entorno: cuénteme sobre su máquina, sistema operativo y versiones de sus paquetes de dependencia.

    • Sus configuraciones: imprima su configuración qteasy y la descripción general de la fuente de datos local

    • Cómo reproducir: intente proporcionarme ejemplos para reproducir el problema y poder identificar su causa raíz.

Proporcionar ejemplos y mejorar los documentos

  • Le agradecería mucho que pudiera proporcionar ejemplos y/o ayudarme con mejoras en los documentos:

    • Estrategias de ejemplo

    • Fragmentos de código

    • Visualizaciones

    • Correcciones de errores

  • Siga el flujo de trabajo de bifurcación/clon/solicitud de extracción a continuación para proporcionar su contribución a qteasy. Intentaré enviar comentarios lo más rápido posible.

Flujo de trabajo de solicitud de bifurcación/clonación/extracción

  • El flujo de trabajo estándar para contribuir en GitHub se llama Fork/Clone. Para aquellos que no estén familiarizados, aquí hay un breve resumen y algunos enlaces de referencia.

    • Asumimos que está familiarizado con los conceptos básicos de git: git clone, git commit, etc..

  • Nota: una «Bifurcación» es solo un git clone que se crea y sigue vivo en GitHub. Creas una bifurcación usando el botón Fork en GitHub: esto le permite a GitHub rastrear la relación entre el repositorio de github original y tu bifurcación.

  • El flujo de trabajo básico es:

    1. Cree una Bifurcación del repositorio qteasy. (Consulte las referencias a continuación para obtener más detalles). La bifurcación existirá en su cuenta de github.

    2. Clonar tu Fork en tu máquina local (git clone).

    3. Trabaja en tu copia clonada del repositorio, git commit los cambios y luego git push ellos a tu bifurcación de GitHub.

    4. Cuando esté satisfecho con el código de su bifurcación, en la página de GitHub de su bifurcación, abra una solicitud de extracción (PR). Una solicitud de extracción solicita efectivamente que los cambios en su bifurcación se introduzcan en el repositorio principal qteasy. El PR proporciona, en github, un lugar para ver los cambios y publicar comentarios y debates sobre ellos.

    5. Después de la revisión del código, si un mantenedor le pide que realice cambios adicionales, no tiene que volver a ingresar otra solicitud de extracción (siempre que el PR original aún esté abierto). Más bien, realice los cambios en su clon local y simplemente git push vuelva a colocarlos en su bifurcación. Los cambios fluirán automáticamente hacia la solicitud de extracción abierta.

    6. Cuando termine, el mantenedor del repositorio fusionará los cambios de su bifurcación en el repositorio qteasy. El PR se cerrará automáticamente. (Sin embargo, su bifurcación seguirá existiendo y podrá usarse nuevamente para solicitudes de extracción adicionales en el futuro; consulte la documentación de GitHub para saber cómo mantener su bifurcación actualizada).

  • Algunas referencias:

  • Documentación de GitHub

    • https://docs.github.com/en/get-started/quickstart/contributing-to-projects

  • y algunas ideas esenciales del usuario

    • https://gist.github.com/Chaser324/ce0505fbed06b947d962

    • https://gist.github.com/rjdmoore/ed014fba0ee2c7e75060ccd01b726cb8

Estándares de codificación

  • No soy muy estricto en cuanto a cumplir con todos los aspectos de PEP 8, ni soy indulgente. Tiendo a caminar por el medio del camino: si algo es bueno y común, entonces hay que respetarlo.

  • Aquí hay algunos elementos que me suelen interesar en particular:

    • Si escribe código, no utilice tabulaciones para la sangría. Utilice 4 espacios.

    • Si escribe código, proporcione siempre comentarios claros y concisos que expliquen lo que hace el código. Esto es especialmente importante para cualquier código que no sea inmediatamente obvio.

    • Si agrega una característica importante, es decir, una característica para la cual explicar su uso requiere más que unas pocas oraciones, cree también un «cuaderno de tutoriales» para esa característica. **[Para ver ejemplos de cuadernos de tutoriales, consulte los cuadernos de jupyter en la carpeta de ejemplos.]

    • Si agrega una característica importante, cree también un archivo de prueba de regresión en la carpeta de pruebas, similar a las otras pruebas de regresión que existen. A menudo, la forma más sencilla de hacerlo es tomar algunos de los ejemplos del «cuaderno de tutoriales» de la función (consulte el punto anterior).

    • Si trabaja en un archivo de código preexistente, intente emular más o menos el estilo que ya existe en ese archivo.