¿Interesado en dar un poco a la comunidad? Quizás ha encontrado un bug en Django que le gustaría ver solucionado, o quizás hay una pequeña característica que quiera agregar.
\nContribuir con Django en sí es la mejor forma de ver abordadas tus propias inquietudes. Esto puede parecer intimidante al principio, pero en realidad es bastante simple. Te guiaremos a través de todo el proceso para que puedas aprender mediante ejemplos.
\nPara este tutorial, esperamos que comprenda al menos el funcionamiento básico de Django. Esto significa que usted no tendría problemas estudiando los tutoriales existentes para crear su primera aplicación Django. Adicionalmente, debería tener una buena comprensión de Python. Si no es así, `Dive into Python`__ es un libro fantástico (y gratuito) disponible en línea para los programadores que comienzan en Python.
\nAquellos de ustedes que no están familiarizados con los sistemas de control de versiones y Trac encontrarán que este tutorial y sus vínculos incluyen información suficiente para empezar. Sin embargo, es probable que quiera leer un poco más acerca de estas diferentes herramientas si usted planea contribuir a Django con regularidad.
\nSin embargo, en su mayor parte, este tutorial trata de explicar tanto como sea posible, de modo que pueda ser de utilidad para la audiencia más amplia.
\n\nTe mostraremos cómo contribuir con parches para Django por primera vez. Al final de este tutorial, contará con un entendimiento básico sobre las herramientas y procesos implicados. Específicamente, cubriremos lo siguiente:
\nInstalando Git.
Descargue una copia de la versión de desarrollo de Django
Conjunto de pruebas de funcionamiento de Django.
Escribiendo una prueba para su parche.
Escribiendo el código para su parche.
Probando su parche.
Enviar una solicitud de pull.
Dónde buscar más información.
Una vez que haya terminado el tutorial, puede revisar el resto de la documentación para contribuir con Django. Contiene una gran cantidad de información de lectura obligatoria para todo el que desee convertirse en colaborador habitual de Django. Si tiene preguntas, es probable que obtenga las respuestas.
\n\n\nComo un colaborador, usted puede ayudarnos a mantener abierta e inclusiva la comunidad Django. Por favor lea y siga nuestro Código de conducta.
\nPara este tutorial, necesitará instalar Git para descargar la versión actual de desarrollo de Django y generar archivos de revisión de los cambios que realice.
\nPara revisar si tiene o no instalado Git , ejecute git en la línea de comandos. Si recibe un mensaje diciendo que el comando no pudo ser encontrado, tendrá que descargarlo e instalarlo, consulte `la página de descarga de Git`__.
Si no estás familiarizado con Git, siempre se puede encontrar más información sobre sus comandos (una vez instalado) escribiendo git help en la línea de comandos.
El primer paso para contribuir con Django es obtener una copia del código fuente. Primero, haz un fork a Django en GitHub. Después, desde la línea de comandos, utiliza en comando cd para navegar hasta el directorio donde querrás que se aloje tu copia local de Django.
Descargue el repositorio de código fuente de Django con el siguiente comando:
\nLinux / macOS
$ git clone git@github.com:YourGitHubName/django.git\nWindows
...\\> git clone git@github.com:YourGitHubName/django.git\nAhora que tiene una copia local de Django, puede instalarla como si fuera a instalar cualquier paquete utilizando pip. La forma más conveniente de hacerlo es mediante un entorno virtual, que es una función incorporada en Python que le permite mantener un directorio separado de paquetes instalados para cada uno de sus proyectos para que no interfieran entre sí.
Es una buena idea mantener todos sus entornos virtuales en un solo lugar, por ejemplo, en `` virtualenvs /`` en su directorio de inicio.
\nCrea un nuevo entorno virtual ejecutando:
\nLinux / macOS
$ python3 -m venv ~/.virtualenvs/djangodev\nWindows
...\\> py -m venv %HOMEPATH%\\.virtualenvs\\djangodev\nLa ruta es donde se guardará el nuevo entorno en su computadora.
\nEl último paso para configurar su entorno virtual es activarlo:
\n$ source ~/.virtualenvs/djangodev/bin/activate\nSi el comando source no está disponible, puede intentar usar un punto en su lugar:
$ . ~/.virtualenvs/djangodev/bin/activate\nDebe activar el entorno virtual cada vez que abra una nueva ventana de terminal. virtualenvwrapper__ es una herramienta útil para hacer esto más conveniente.
\nEl nombre del entorno virtual actualmente activado se muestra en la línea de comandos para ayudarlo a realizar un seguimiento de cuál está utilizando. Todo lo que instales a través de pip mientras se muestre este nombre se instalará en ese entorno virtual, aislado de otros entornos y paquetes del systema.
Continúa e instala la copia previamente clonada de Django:
\nLinux / macOS
$ pip install -e /path/to/your/local/clone/django/\nWindows
...\\> pip install -e \\path\\to\\your\\local\\clone\\django\\\nLa versión instalada de Django está señalando su copia local. Inmediatamente verá los cambios que le realice a la misma, lo cual será de gran ayuda cuando escriba su primer parche.
\nAl contribuir con Django, es muy importante que los cambios en el código no introduzcan errores en otras áreas de Django. Una forma de comprobar que Django aún funciona después de realizar los cambios es ejecutando el conjunto de pruebas de Django. Si todas las pruebas aún pasan, entonces puede estar razonablemente seguro de que sus cambios funcionan y no ha roto otras partes de Django. Si nunca ha ejecutado la suite de prueba de Django antes, es una buena idea ejecutarla una vez antes para familiarizarse con su salida.
\nAntes de ejecutar el conjunto de pruebas, instale sus dependencias, primero cambiándo al directorio tests/ de Django y después ejecutando:
Linux / macOS
$ pip install -r requirements/py3.txt\nWindows
...\\> pip install -r requirements\\py3.txt\nSi encuentra un error durante la instalación, puede que su sistema carezca de alguna dependencia para uno o más de los paquetes de Python. Consulte la documentación del paquete que falla o busque en la web el mensaje de error que encuentre.
\nAhora estamos listos para ejecutar el conjunto de pruebas. Si estás utilizando GNU/Linux, macOS o alguna otra distribución de Unix, ejecuta:
\nLinux / macOS
$ ./runtests.py\nWindows
...\\> runtests.py \nAhora siéntate y relájate. El conjunto completo de pruebas de Django tiene miles de pruebas diferentes, así que puede tardar al menos cinco minutos, dependiendo de la velocidad de su ordenador.
\nMientras se ejecuta la suite de pruebas de Django, verá una secuencia de caracteres que representan el estado de cada prueba a medida que se completa. `` E`` indica que un error se planteó durante una prueba, y `` F`` indica las afirmaciones de una prueba fallida. Ambos de estos son considerados como fallas de prueba. Mientras tanto, `` x`` y `` s`` indicaron fallas esperadas y pruebas omitidas, respectivamente. Los puntos indican pruebas superadas.
\nLas pruebas omitidas se deben usualmente a la ausencia de bibliotecas externas requeridas para la ejecución de los test; ver Running all the tests para la lista de dependencias y estar seguro de instalar aquellas relacionadas con los cambios que estás haciendo (no necesitamos ninguna para esta tutorial). Algunas pruebas son especificas de un backend de base de datos particular y serán omitidas si no se está probando ese backend. SQLite es el backend por defecto para las pruebas. Para ejecutar las pruebas con un backend diferente ver Using another settings module.
\nUna vez que las pruebas finalicen, usted debe ser recibido con un mensaje que le informa si el conjunto de pruebas pasó o falló. Dado que aún no ha realizado ningún cambio en el código de Django, todo el conjunto de pruebas debe pasar. Si obtiene fallos o errores asegúrese de que ha seguido correctamente todos los pasos anteriores . Consulte: ref: Ejecutar pruebas unitarias para más información.
\nTenga en cuenta que la última versión de Django en master no siempre es estable. Cuando se desarrolla en master, puede comprobar `la integración continua de Django`__ para determinar si los fallos son propios de su sistema o se encuentran también presentes en la versión oficial. Si hace clic para ver una versión en particular, usted puede ver la «Matriz de configuración», que muestra los fallos analizados por la versión de Python y el backend de la base de datos.
\n\nPara este tutorial, trabajaremos sobre un «falso ticket» como un caso de estudio. Estos son los datos imaginarios:
\n\nBueno, ahora implemente la característica y sus tests asociados.
\nAntes de hacer ningún cambio, cree una nueva rama para el ticket:
\nLinux / macOS
$ git checkout -b ticket_99999\nWindows
...\\> git checkout -b ticket_99999\nYou can choose any name that you want for the branch, «ticket_99999» is an\nexample. All changes made in this branch will be specific to the ticket and\nwon’t affect the main copy of the code that we cloned earlier.
\nEn la mayoría de los casos, para que un parche sea aceptado en Django tiene que incluir pruebas. Para los parches de corrección de bugs, esto significa escribir una prueba de regresión para asegurar que el bug no sea reintroducido en Django más adelante. Una prueba de regresión debe ser escrita de forma tal que falle mientras que todavía exista el bug y pase una vez que el bug se haya corregido. Para los parches que contienen nuevas características, tendrás que incluir pruebas que garanticen que dichas características estén funcionando correctamente. Los parches también deben fallar cuando la nueva característica no esté presente y por lo tanto, pasar una vez que haya sido aplicada.
\nUna buena forma de hacer esto, es escribir primero sus nuevas pruebas antes de realizar cualquier cambio en el código. Este estilo de desarrollo se llama `desarrollo guiado por pruebas`__ y se puede aplicar tanto a proyectos completos como a parches individuales. Después de escribir sus pruebas, ejecútelas para asegurarse de que en efecto fallan (ya que aún no ha corregido ese bug o añadido esa característica). Si sus nuevas pruebas no fallan, tendrá que arreglarlas de manera que lo hagan. Después de todo, una prueba de regresión que pasa sin importar si un error está presente, no es muy útil en prevenir que ese error se repita en el futuro.
\nAhora a nuestro ejemplo práctico.
\nIn order to resolve this ticket, we’ll add a make_toast() function to the\ntop-level django module. First we are going to write a test that tries to\nuse the function and check that its output looks correct.
Navega a la carpeta tests/shortcuts/ y crea un nuevo fichero llamado test_make_toast.py. Añade el siguiente código:
from django.shortcuts import make_toast\nfrom django.test import SimpleTestCase\n\n\nclass MakeToastTests(SimpleTestCase):\n def test_make_toast(self):\n self.assertEqual(make_toast(), 'toast')\nThis test checks that the make_toast() returns 'toast'.
Since we haven’t made any modifications to django.shortcuts yet, our test\nshould fail. Let’s run all the tests in the shortcuts folder to make sure\nthat’s really what happens. cd to the Django tests/ directory and run:
Linux / macOS
$ ./runtests.py shortcuts\nWindows
...\\> runtests.py shortcuts\nIf the tests ran correctly, you should see one failure corresponding to the test\nmethod we added, with this error:
\nImportError: cannot import name 'make_toast' from 'django.shortcuts'\nIf all of the tests passed, then you’ll want to make sure that you added the\nnew test shown above to the appropriate folder and file name.
\nNext we’ll be adding the make_toast() function.
Navigate to the django/ folder and open the shortcuts.py file. At the\nbottom, add:
def make_toast():\n return 'toast'\nNow we need to make sure that the test we wrote earlier passes, so we can see\nwhether the code we added is working correctly. Again, navigate to the Django\ntests/ directory and run:
Linux / macOS
$ ./runtests.py shortcuts\nWindows
...\\> runtests.py shortcuts\nEverything should pass. If it doesn’t, make sure you correctly added the\nfunction to the correct file.
\nUna vez que haya verificado que su parche y su prueba funcionan correctamente, es una buena idea ejecutar todo el conjunto de pruebas de Django sólo para comprobar que su cambio no ha introducido ningún bug en otras áreas de Django. A pesar de que pasar con éxito todo el conjunto de pruebas no garantiza que su código está libre de errores, sí ayuda a identificar muchos bugs y regresiones que de otro modo podrían pasar desapercibidos.
\nPara ejecutar todo el conjunto de pruebas de Django, cambie al directorio tests/ de Django y ejecute:
Linux / macOS
$ ./runtests.py\nWindows
...\\> runtests.py \nThis is a new feature, so it should be documented. Open the file\ndocs/topics/http/shortcuts.txt and add the following at the end of the\nfile:
``make_toast()``\n================\n\n.. versionadded:: 2.2\n\nReturns ``'toast'``.\nSince this new feature will be in an upcoming release it is also added to the\nrelease notes for the next version of Django. Open the release notes for the\nlatest version in docs/releases/, which at time of writing is 2.2.txt.\nAdd a note under the «Minor Features» header:
:mod:`django.shortcuts`\n~~~~~~~~~~~~~~~~~~~~~~~\n\n* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.\nPara obtener más información sobre escribir la documentación, incluyendo una explicación de lo que se trata el fragmento versionadded, consulte Writing documentation. Esa página incluye también una explicación de cómo generar una copia de la documentación localmente, por lo que puede obtener una vista previa del código HTML que se generará.
Now it’s time to go through all the changes made in our patch. To stage all the\nchanges ready for commit, run:
\nLinux / macOS
$ git add --all\nWindows
...\\> git add --all\nThen display the differences between your current copy of Django (with your\nchanges) and the revision that you initially checked out earlier in the\ntutorial with:
\nLinux / macOS
$ git diff --cached\nWindows
...\\> git diff --cached\nUse las flechas del teclado para moverse arriba y abajo.
\ndiff --git a/django/shortcuts.py b/django/shortcuts.py\nindex 7ab1df0e9d..8dde9e28d9 100644\n--- a/django/shortcuts.py\n+++ b/django/shortcuts.py\n@@ -156,3 +156,7 @@ def resolve_url(to, *args, **kwargs):\n\n # Finally, fall back and assume it's a URL\n return to\n+\n+\n+def make_toast():\n+ return 'toast'\ndiff --git a/docs/releases/2.2.txt b/docs/releases/2.2.txt\nindex 7d85d30c4a..81518187b3 100644\n--- a/docs/releases/2.2.txt\n+++ b/docs/releases/2.2.txt\n@@ -40,6 +40,11 @@ database constraints. Constraints are added to models using the\n Minor features\n --------------\n\n+:mod:`django.shortcuts`\n+~~~~~~~~~~~~~~~~~~~~~~~\n+\n+* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.\n+\n :mod:`django.contrib.admin`\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\ndiff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt\nindex 7b3a3a2c00..711bf6bb6d 100644\n--- a/docs/topics/http/shortcuts.txt\n+++ b/docs/topics/http/shortcuts.txt\n@@ -271,3 +271,12 @@ This example is equivalent to::\n my_objects = list(MyModel.objects.filter(published=True))\n if not my_objects:\n raise Http404("No MyModel matches the given query.")\n+\n+``make_toast()``\n+================\n+\n+.. function:: make_toast()\n+\n+.. versionadded:: 2.2\n+\n+Returns ``'toast'``.\ndiff --git a/tests/shortcuts/test_make_toast.py b/tests/shortcuts/test_make_toast.py\nnew file mode 100644\nindex 0000000000..6f4c627b6e\n--- /dev/null\n+++ b/tests/shortcuts/test_make_toast.py\n@@ -0,0 +1,7 @@\n+from django.shortcuts import make_toast\n+from django.test import SimpleTestCase\n+\n+\n+class MakeToastTests(SimpleTestCase):\n+ def test_make_toast(self):\n+ self.assertEqual(make_toast(), 'toast')\nCuando hayas terminado de revisar el parche presiona q para volver a la línea de comandos. Si el contenido del parche se veía bien es tiempo de consumar los cambios.
Para consumar los cambios:
\nLinux / macOS
$ git commit\nWindows
...\\> git commit\nEsto abre un editor de texto para escribir el mensaje del commit. Sigue las guías para mensajes del commit y escribe un mensaje como:
\nFixed #99999 -- Added a shortcut function to make toast.\nAfter committing the patch, send it to your fork on GitHub (substitute\n«ticket_99999» with the name of your branch if it’s different):
\nLinux / macOS
$ git push origin ticket_99999\nWindows
...\\> git push origin ticket_99999\nPuedes crear una solicitud de pull visitando La página GitHub de Django. Vas a ver tu rama en «Your recently pushed branches». Has clic en «Compare & pull request».
\nPor favor no lo hagas para este tutorial, pero en la siguiente página muestra una vista previa del parche, deberías hacer clic en «Create pull request».
\n¡Enhorabuena, ha aprendido cómo hacer una solicitud de pull a Django! Encontrará detalles de técnicas más avanzadas que puede necesitar en Working with Git and GitHub.
\nAhora puedes dar un buen uso a esas habilidades ayudando a mejorar la base de código de Django.
\nAntes de que se involucre mucho en la escritura de parches para Django, hay algo más de información sobre cómo contribuir a la que probablemente debería echarle un vistazo:
\nDebe asegurarse de leer la documentación de Django sobre reclamar tickets y enviar parches. Esta incluye la etiqueta de Trac, cómo reclamar tickets para uno mismo, el estilo esperado de codificación para parches y muchos otros detalles importantes.
Las personas que colaboran por primera vez también deben leer la documentación para los colaboradores principiantes de Django. Tiene muchos buenos consejos para aquellos de nosotros que somos nuevos en esto de colaborar con Django.
Después de ellos, si todavía quiere más información sobre cómo contribuir, siempre se puede navegar por el resto de la documentación de Django sobre cómo contribuir. Este contiene un montón de información útil y debe ser su primera fuente para responder a cualquier pregunta que pueda tener.
Una vez que haya revisado parte de esa información, estará listo para salir y encontrar un ticket al cual escribirle un parche. Preste especial atención a los tickets con el criterio de «easy pickings». Estos tickets son a menudo de carácter mucho más simples y son geniales para los que colaboran por primera vez. Una vez que esté familiarizado con como contribuir con Django, puede pasar a escribir parches para los tickets más difíciles y complicados.
\nSi lo que desea es empezar ya (¡Y nadie lo culparía!), trate de echar un vistazo a la lista de `los tickets sencillos que necesitan parches`__ y `los tickets sencillos que tienen parches que necesitan mejoras`__. Si se siente cómodo con la escritura de pruebas también puede ver la lista de “tickets sencillos que necesitan pruebas`__. Sólo recuerde seguir las directrices sobre cómo reclamar tickets que se mencionaron en el enlace a la documentación de Django sobre reclamar tickets y enviar parches.
\nDespués de que un ticket tiene un parche, necesita ser revisado por un segundo par de ojos. Después de enviar una solicitud de pull asegúrese de actualizar los metadatos del ticket mediante el establecimiento de banderas en el ticket para decir «tiene parche», «no necesita pruebas», etc, para que otros puedan encontrarlo para su revisión. Contribuir no necesariamente siempre significa escribir un parche desde cero. Revisar parches existentes es también una contribución muy útil. Consulte: doc:/internals/contributing/triaging-tickets para más detalles.
\n