Resumen

Todos los cambios en el código y la documentación deben ser (/contributing/first-time/github/) a través de una pull request al repositorio de repositorio GitHub del proyecto.

La mayoría de los proyectos cuentan con una guía de contribución específica para ese proyecto, o tipos específicos de contribución. Esta documentación puede encontrarse en Read the Docs. Por ejemplo, Briefcase's documentación contiene guías de contribución tanto para código y documentación.

Todos los envíos deben atenerse al Código de conducta de BeeWare Conducta.

Notas de cambio

Varios proyectos BeeWare, en particular Briefcase y Toga, requieren que cada pull request se envíe con una nota de cambio. Estas notas de cambio son compiladas cuando se corta una nueva versión para el proyecto, produciendo las notas de la nueva versión.

BeeWare utiliza Towncrier para gestionar las notas de cambio.

Se debe crear un archivo de notas de cambio en el directorio changes y con este formato:

<PR/Issue #>.<Change Type>.rst

Por ejemplo, un pull request que corrige el problema #42 de GitHub se llamaría 42.bugfix.rst. Si un pull request no está asociado a una incidencia se puede utilizar el número de la solicitud de extracción. Puede que necesite crear el pull request sin una nota de cambio para obtener un número de pull request pull request asignado, y luego enviar una actualización que incluya la nota de cambio con con el número de pull request recién asignado.

Las clases de modificación para la nota de modificación deben ser una de las siguientes:

  • `característica
  • corrección de errores
  • `documento
  • eliminación
  • Miscelánea

El tipo misc está reservado para los cambios que no afectan a los usuarios, y no es necesario indicarlos en las notas de la versión. Correcciones tipográficas menores en la documentación, actualizaciones de la configuración de CI y correcciones de errores para características que aún no se han publicado formalmente son ejemplos de características que se describirían utilizando marcadores misc.

Una nota de cambio debe ser una sola línea de texto, que proporcione un resumen de alto nivel del cambio desde la perspectiva del usuario. de alto nivel del cambio desde la perspectiva del usuario, no una descripción descripción técnica o detalles de implementación. Es distinta de un mensaje de confirmación. Un mensaje de confirmación describe lo que se ha hecho para que futuros desarrolladores puedan seguir el razonamiento de un cambio. Una nota de cambio es una descripción "de cara al usuario", descrita en términos de la nueva capacidad disponible como resultado del cambio. Puede ser útil pensar en la nota de cambio como un comunicado de prensa anunciando el cambio, en lugar de una descripción del commit.

Por ejemplo, si corrige un error causado por el manejo de fechas, el mensaje de confirmación o la descripción de la solicitud de extracción podría ser:

Añadido un validador de formato MM-DD-YYYY a la cadena de validación DateWidget cadena.

Describe el cambio realizado en la implementación - detalle que será útil para la persona que revise el código. Sin embargo, la nota de cambio correspondiente podría decir algo como:

Los widgets de fecha ahora pueden aceptar fechas en formato US.

Describe el cambio funcional tal y como lo experimentarán los usuarios finales. usuarios finales. Un usuario puede leer esta descripción sin necesidad de saber nada sobre la implementación.

Código de estilo

Los proyectos de BeeWare utilizan Pre-commit para automatizar la adherencia al estilo del código. Estas comprobaciones se definen en el archivo archivo .pre-commit-config.yaml para cada repositorio y son automáticamente automáticamente en CI cuando se abre un Pull Request. se abre.

Para automatizar las comprobaciones Pre-commit en tu entorno de desarrollo local con cada commit de git, ejecute pre-commit install.

Incluye comprobaciones previas al compromiso:

Directrices adicionales:

  • Evitar el uso de "nosotros" en los comentarios, por ejemplo, "Loop over" en lugar de "We loop sobre".

  • Utilice guiones bajos, no camelCase, para los nombres de variables, funciones y métodos. nombres

  • Utilice InitialCaps para los nombres de clases (o para las funciones de fábrica que devuelven clases)

  • Use docstrings estilo Sphinx y 257; la anotación de tipo con 484 es opcional pero recomendable.

    Por ejemplo:

    def nombre_funcion(param1: int, param2: str) -> bool:
    """Función de ejemplo con tipos y un docstring.

    :param param1: El primer parámetro.
    :param param2: El segundo parámetro.

    :devuelve: El valor de retorno. True para éxito, False en caso contrario.
    """

  • En la documentación de las pruebas, indique el comportamiento esperado que cada prueba prueba. No incluya preámbulos como "Prueba que" o "Garantiza que". que".

  • Reservar las referencias de los tickets para problemas oscuros en los que el ticket tiene detalles adicionales que no pueden describirse fácilmente en docstrings o comentarios. Incluya el número de ticket al final de una frase como así:

    def prueba_foo():
    """Un docstring de prueba tiene este aspecto (#123456)."""

  • A menos que se especifique lo contrario, siga 8 (prestando especial atención a Sección 2).