Cómo contribuir a Flask

¡Gracias por considerar la posibilidad de contribuir a Flask!

Preguntas de apoyo

Por favor, no utilices el rastreador de problemas para esto. El rastreador de problemas es una herramienta para abordar los errores y las solicitudes de características en el propio Flask. Utiliza uno de los siguientes recursos para preguntas sobre el uso de Flask o problemas con tu propio código:

  • El canal #questions en nuestro chat de Discord: https://discord.gg/pallets

  • Pregunta en Stack Overflow. Busca con Google primero usando: site:stackoverflow.com flask {término de búsqueda, mensaje de excepción, etc.}

  • Pregunte en nuestro GitHub Discussions para discusiones a largo plazo o preguntas más amplias.

Informar de los problemas

Incluya la siguiente información en su puesto:

  • Describa lo que esperaba que ocurriera.

  • Si es posible, incluye un ejemplo mínimo reproducible para ayudarnos a identificar el problema. Esto también ayuda a comprobar que el problema no es con su propio código.

  • Describa lo que realmente sucedió. Incluya el rastreo completo si hubo una excepción.

  • Enumera tus versiones de Python y Flask. Si es posible, comprueba si este problema ya está solucionado en las últimas versiones o en el último código del repositorio.

Envío de parches

Si no hay un tema abierto para lo que quieres enviar, prefiere abrir uno para su discusión antes de trabajar en un PR. Puedes trabajar en cualquier tema que no tenga un PR abierto vinculado o un mantenedor asignado. Estos aparecen en la barra lateral. No hace falta que preguntes si puedes trabajar en un tema que te interesa.

Incluya lo siguiente en su parche:

  • Utilice Black para formatear su código. Esta y otras herramientas se ejecutarán automáticamente si instalas pre-commit siguiendo las instrucciones que aparecen a continuación.

  • Incluya pruebas si su parche añade o cambia código. Asegúrese de que la prueba falla sin su parche.

  • Actualice las páginas de documentos y las cadenas de documentos pertinentes. Las páginas de documentos y las cadenas de documentos deben tener 72 caracteres.

  • Añade una entrada en CHANGES.rst. Utilice el mismo estilo que otras entradas. Incluir también . versionchanged:: inline changelogs en los docstrings relevantes.

Primera configuración

  • Descargue e instale la última versión de git.

  • Configura git con tu nombre de usuario y correo electrónico.

    $ git config --global user.name 'your name'
    $ git config --global user.email 'your email'
    
  • Asegúrate de tener una cuenta en GitHub.

  • Fork Flask a su cuenta de GitHub haciendo clic en el botón Fork.

  • Clona el repositorio principal localmente.

    $ git clone https://github.com/pallets/flask
    $ cd flask
    
  • Añade tu fork como remoto para empujar tu trabajo. Sustituye {username} por tu nombre de usuario. Esto nombra al remoto «fork», el remoto por defecto de Pallets es «origin».

    $ git remote add fork https://github.com/{username}/flask
    
  • Crear un virtualenv.

    • Linux/macOS

      $ python3 -m venv env
      $ . env/bin/activate
      
    • Windows

      > py -3 -m venv env
      > env\Scripts\activate
      
  • Actualizar pip y setuptools.

    $ python -m pip install --upgrade pip setuptools
    
  • Instale las dependencias de desarrollo y luego instale Flask en modo editable.

    $ pip install -r requirements/dev.txt && pip install -e .
    
  • Instale los hooks de pre-commit.

    $ pre-commit install
    

Empezar a codificar

  • Crea una rama para identificar el problema en el que te gustaría trabajar. Si estás enviando una corrección de un error o de la documentación, bifurca desde la última rama «.x».

    $ git fetch origin
    $ git checkout -b your-branch-name origin/2.0.x
    

    Si estás enviando una adición o cambio de característica, bifúrcate de la rama «main».

    $ git fetch origin
    $ git checkout -b your-branch-name origin/main
    
  • Utilizando su editor favorito, realice los cambios, hacer commits a medida que avanza.

  • Incluya pruebas que cubran cualquier cambio de código que realice. Asegúrese de que la prueba falla sin su parche. Ejecute las pruebas como se describe a continuación.

  • Empuja tus commits a tu fork en GitHub y crea un pull request. Enlaza el problema que se está tratando con fixes #123 en el pull request.

    $ git push --set-upstream fork your-branch-name
    

Ejecución de las pruebas

Ejecute el conjunto de pruebas básicas con pytest.

$ pytest

Esto ejecuta las pruebas para el entorno actual, que suele ser suficiente. CI ejecutará el conjunto completo cuando envíe su solicitud de extracción. Puede ejecutar el conjunto completo de pruebas con tox si no quiere esperar.

$ tox

Ejecución de la cobertura de las pruebas

Generar un informe de las líneas que no tienen cobertura de pruebas puede indicar por dónde empezar a contribuir. Ejecuta pytest utilizando coverage y genera un informe.

$ pip install coverage
$ coverage run -m pytest
$ coverage html

Abra htmlcov/index.html en su navegador para explorar el informe.

Más información sobre cobertura.

Construir los documentos

Construye los documentos en el directorio docs usando Sphinx.

$ cd docs
$ make html

Abre _build/html/index.html en tu navegador para ver los documentos.

Más información sobre Sphinx.