Interested in giving back to the community a little? Maybe you’ve found a bug\nin Django that you’d like to see fixed, or maybe there’s a small feature you\nwant added (but remember that proposals for new features should follow the\nprocess for suggesting new features).
\nContribuyendo al propio proyecto de Django es la mejor forma de ver sus propios problemas abordados. Puede parecer desalentador al inicio, pero es un camino ya conocido: con documentación, herramientas, y una comunidad que le ayudará. Le guiaremos por todo el proceso, así pueda aprender con el ejemplo.
\nPara este tutorial, esperamos que tenga al menos un entendimiento básico de cómo funciona Django. Esto significa que debe sentirse cómodo al repasar los tutoriales que se encuentran en escribiendo su primer aplicación de Django. Además, debe tener una buena comprensión de Python. Pero si no la tiene, Dive Into Python es un fantástico (y gratuito) libro en línea para programadores Python principiantes.
\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\nWe’ll be walking you through contributing to Django for the first time. By the\nend of this tutorial, you should have a basic understanding of both the tools\nand the processes involved. Specifically, we’ll be covering the following:
\nInstalando Git.
Descargue una copia de la versión de desarrollo de Django
Conjunto de pruebas de funcionamiento de Django.
Escribiendo un prueba para sus cambios
Escribiendo el código para sus cambios
Pruebe sus cambios.
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\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 de desarrollo actual de Django y generar una rama para 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á 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, haga un fork de Django en GitHub. Después, desde la línea de comandos, use el comando cd para navegar hasta el directorio donde quiera que se aloje su copia local de Django.
Descargue el repositorio de código fuente de Django con el siguiente comando:
\nLinux / macOS
$ git clone https://github.com/YourGitHubName/django.git\nWindows
...\\> git clone https://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.
Cree 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 la terminal.
\n\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 instale a través de pip mientras se muestre este nombre se instalará en ese entorno virtual, aislado de otros entornos y paquetes del sistema.
Continúe e instale la copia previamente clonada de Django:
\nLinux / macOS
$ python -m pip install -e /path/to/your/local/clone/django/\nWindows
...\\> py -m pip install -e \\path\\to\\your\\local\\clone\\django\\\nThe installed version of Django is now pointing at your local copy by\ninstalling in editable mode. You will immediately see any changes you make to\nit, which is of great help when testing your first contribution.
\nCuando contribuya a Django, es muy importante que sus cambios de código no introduzcan errores en otras áreas de Django. Una forma de comprobar que Django sigue funcionando después de hacer sus cambios es ejecutar la suite de pruebas de Django. Si todas las pruebas siguen pasando, entonces puedes estar razonablemente seguro de que sus cambios funcionan y no han roto otras partes de Django. Si nunca ha ejecutado la suite de pruebas de Django antes, es una buena idea ejecutarla una vez antes para familiarizarse con su salida.
\nAntes de ejecutar el conjunto de pruebas, ingrese al directorio de Django tests/ utilizando el comando cd tests y instale las dependencias de prueba ejecutando:
Linux / macOS
$ python -m pip install -r requirements/py3.txt\nWindows
...\\> py -m pip install -r requirements\\py3.txt\nSi encuentra un error durante la instalación, es posible que a su sistema le falte una 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 la suite de prueba:
\nLinux / macOS
$ ./runtests.py\nWindows
...\\> runtests.py \nAhora siéntese y relájese. La suite de pruebas completa de Django tiene miles de pruebas y tarda al menos unos minutos en ejecutarse, dependiendo de la velocidad de su computadora.
\nWhile Django’s test suite is running, you’ll see a stream of characters\nrepresenting the status of each test as it completes. E indicates that an\nerror was raised during a test, and F indicates that a test’s assertions\nfailed. Both of these are considered to be test failures. Meanwhile, x and\ns indicate expected failures and skipped tests, respectively. Dots indicate\npassing tests.
Las pruebas omitidas se deben usualmente a la ausencia de bibliotecas externas requeridas para la ejecución de las pruebas; ver Running all the tests para la lista de dependencias y estar seguro de instalar aquellas relacionadas con los cambios que está 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 debería recibir un mensaje informándole 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 debería pasar. Si obtiene fallos o errores, asegúrese de que ha seguido correctamente todos los pasos anteriores . Consulte Running the unit tests para más información.
\nTen en cuenta que la última rama «main» de Django no siempre es estable. Cuando desarrolles contra «main», puedes comprobar Django’s continuous integration builds para determinar si los fallos son específicos de tu máquina o si también están presentes en las builds oficiales de Django. Si haces clic para ver una compilación en particular, verás la «Matriz de configuración» que muestra los fallos desglosados por versión de Python y backend de base de datos específicos.
\n\nFor this tutorial, we’ll work on a «fake accepted ticket» as a case study. Here\nare the imaginary details:
\n\nBueno, ahora implemente la característica y sus pruebas asociadas.
\nAntes de hacer algún cambio, cree una nueva rama para el ticket:
\nLinux / macOS
$ git checkout -b ticket_99999\nWindows
...\\> git checkout -b ticket_99999\nPuede elegir cualquier nombre que desee para la rama, por ejemplo «ticket_99999». Todos los cambios realizados en esta rama será específico para el ticket y no afecta la copia principal del código previamente clonado
\nIn most cases, for a contribution to be accepted into Django it has to include\ntests. For bug fix contributions, this means writing a regression test to\nensure that the bug is never reintroduced into Django later on. A regression\ntest should be written in such a way that it will fail while the bug still\nexists and pass once the bug has been fixed. For contributions containing new\nfeatures, you’ll need to include tests which ensure that the new features are\nworking correctly. They too should fail when the new feature is not present,\nand then pass once it has been implemented.
\nA good way to do this is to write your new tests first, before making any\nchanges to the code. This style of development is called\ntest-driven development and can be applied to both entire projects and\nsingle changes. After writing your tests, you then run them to make sure that\nthey do indeed fail (since you haven’t fixed that bug or added that feature\nyet). If your new tests don’t fail, you’ll need to fix them so that they do.\nAfter all, a regression test that passes regardless of whether a bug is present\nis not very helpful at preventing that bug from reoccurring down the road.
\nAhora a nuestro ejemplo práctico.
\nPara resolver este problema, vamos a añadir una función make_toast() al módulo django.shortcuts. Primero vamos a escribir un test que intente usar la función y comprobar que su salida parezca correcta.
Navegue a la carpeta tests/shortcuts/ y cree un nuevo fichero llamado test_make_toast.py. Añada 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")\nEsta prueba comprueba que la función make_toast() devuelve 'toast'
Ya que no hemos hecho ninguna modificación en django.shortcuts, nuestra prueba debería fallar. Vamos a ejecutar todas las pruebas en la carpeta shortcuts para asegurarnos de que es lo que realmente ocurre. Use cd para cambiarse al directorio tests/ de Django y ejecute:
Linux / macOS
$ ./runtests.py shortcuts\nWindows
...\\> runtests.py shortcuts\nSi las pruebas se ejecutaron correctamente, debería ver un fallo correspondiente al método de prueba que agregamos, con este error:
\nImportError: cannot import name 'make_toast' from 'django.shortcuts'\nSi todos las pruebas pasaron, entonces querrá asegurarse de haber agregado la nueva prueba mostrada arriba a la carpeta y nombre de archivo correspondiente.
\nAhora agregaremos la función make_toast().
Navegue al directorio django/ y edite shortcuts.py. Al final del archivo añada:
def make_toast():\n return "toast"\nAhora necesitamos asegurarnos de que la prueba que escribimos anteriormente pase, para poder ver si el código que agregamos funciona correctamente. Nuevamente, navegue al directorio tests/ de Django y ejecute:
Linux / macOS
$ ./runtests.py shortcuts\nWindows
...\\> runtests.py shortcuts\nTodo debería funcionar. Si no lo hace, asegúrese de haber agregado correctamente la función al archivo correcto.
\nOnce you’ve verified that your changes and test are working correctly, it’s\na good idea to run the entire Django test suite to verify that your change\nhasn’t introduced any bugs into other areas of Django. While successfully\npassing the entire test suite doesn’t guarantee your code is bug free, it does\nhelp identify many bugs and regressions that might otherwise go unnoticed.
\nPara ejecutar todo el conjunto de pruebas de Django, cambie al directorio tests/ de Django y ejecute:
Linux / macOS
$ ./runtests.py\nWindows
...\\> runtests.py \nEsta es una nueva funcionalidad, por tlo anto debe ser documentada. Edite docs/topics/http/shortcuts.txt y agregue lo siguiente al final del archivo:
``make_toast()``\n================\n\n.. function:: make_toast()\n\n.. versionadded:: 2.2\n\nReturns ``'toast'``.\nDado que esta nueva característica estará en una próxima versión, también se agrega a las notas de la versión para la próxima versión de Django. Abra las notas de la versión más reciente en docs/releases/, que en el momento de escribir esto es 2.2.txt. Agregue una nota debajo del encabezado «Minor Features».
: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á.
Ahora es momento de revisar los cambios realizados en la rama. Para preparar todos los cambios que estén listos para la confirmación, ejecute:
\nLinux / macOS
$ git add --all\nWindows
...\\> git add --all\nLuego muestra las diferencias entre su copia actual de Django (con sus cambios) y la revisión que inicialmente verificó anteriormente en el tutorial con:
\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')\nWhen you’re done previewing the changes, hit the q key to return to the\ncommand line. If the diff looked okay, it’s time to commit the changes.
Para confirmar los cambios:
\nLinux / macOS
$ git commit\nWindows
...\\> git commit\nEsto abre un editor de texto para escribir el mensaje de confirmación. Siga las guías para mensajes de confirmación y escriba un mensaje como:
\nFixed #99999 -- Added a shortcut function to make toast.\nAfter committing the changes, 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\nPuede crear una solicitud de fusión visitando La página GitHub de Django. Verá su rama en «Your recently pushed branches». Haga clic en «Compare & pull request».
\nPlease don’t do it for this tutorial, but on the next page that displays a\npreview of the changes, you would click «Create pull request».
\n¡Enhorabuena, ha aprendido cómo hacer una solicitud de fusión 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.
\nBefore you get too into contributing to Django, there’s a little more\ninformation on contributing that you should probably take a look at:
\nYou should make sure to read Django’s documentation on\nclaiming tickets and submitting pull requests.\nIt covers Trac etiquette, how to claim tickets for yourself, expected\ncoding style (both for code and docs), and many other important details.
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.
Once you’ve looked through some of that information, you’ll be ready to go out\nand find a ticket of your own to contribute to. Pay special attention to\ntickets with the «easy pickings» criterion. These tickets are often much\nsimpler in nature and are great for first time contributors. Once you’re\nfamiliar with contributing to Django, you can start working on more difficult\nand complicated tickets.
\nIf you just want to get started already (and nobody would blame you!), try\ntaking a look at the list of easy tickets without a branch and the\neasy tickets that have branches which need improvement. If you’re familiar\nwith writing tests, you can also look at the list of\neasy tickets that need tests. Remember to follow the guidelines about\nclaiming tickets that were mentioned in the link to Django’s documentation on\nclaiming tickets and submitting branches.
\nAfter a ticket has a branch, it needs to be reviewed by a second set of eyes.\nAfter submitting a pull request, update the ticket metadata by setting the\nflags on the ticket to say «has patch», «doesn’t need tests», etc, so others\ncan find it for review. Contributing doesn’t necessarily always mean writing\ncode from scratch. Reviewing open pull requests is also a very helpful\ncontribution. See Clasificando tickets for details.
\n