¿Te interesa devolver algo a la comunidad? Quizás hayas encontrado un bug en Django que te gustaría ver corregido, o quizás haya una pequeña característica que desees agregar (pero recuerda que las propuestas de nuevas características deben seguir el proceso para sugerir nuevas características).
Contribuir a Django en sí mismo es la mejor manera de ver tus propias preocupaciones abordadas. Esto puede parecer intimidante al principio, pero es un camino bien transitado con documentación, herramientas y una comunidad que te apoye. Te guiamos por todo el proceso, para que puedas aprender por ejemplo.
Ver también
Si buscas una referencia sobre los detalles de hacer contribuciones de código, consulta la documentación Contribuir código.
Para este tutorial, esperamos que tengas al menos una comprensión básica de cómo funciona Django. Esto significa que deberías estar cómodo pasando por los tutoriales existentes sobre escribiendo tu primera aplicación de Django. Además, debes tener una buena comprensión del propio Python. Pero si no es así, Dive Into Python es un fantástico (y gratuito) libro en línea para programadores principiantes de Python.
Aquellos de ustedes que están desconocidos con sistemas de control de versiones y Trac encontrarán que este tutorial y sus enlaces incluyen suficiente información para empezar. Sin embargo, probablemente desees leer más sobre estas herramientas diferentes si planeas contribuir a Django regularmente.
En general, sin embargo, este tutorial trata de explicar lo máximo posible, para que pueda ser útil para el público más amplio.
¿Dónde obtener ayuda:
Si tienes problemas para seguir este tutorial, por favor publica un mensaje en el Django Forum o pasa por el servidor de Discord de Django para charlar con otros usuarios de Django que pueden ayudarte.
Recorreremos contigo cómo contribuir a Django por primera vez. Al finalizar este tutorial, deberías tener una comprensión básica tanto de las herramientas como de los procesos involucrados. Específicamente, cubriremos lo siguiente:
Instalar Git.
Descargar una copia de la versión de desarrollo de Django.
Ejecutar el conjunto de pruebas de Django.
Escribir una prueba para tus cambios.
Escribir el código para tus cambios.
Probar tus cambios.
Enviar una solicitud de extracción.
Dónde buscar más información.
Una vez que hayas terminado con el tutorial, puedes revisar el resto de la documentación de Django sobre contribución. Contiene mucha información útil y es un must read para cualquier persona que desee convertirse en un contribuyente regular de Django. Si tienes preguntas, probablemente tenga las respuestas.
¡Requiere Python 3!
La versión actual de Django no soporta Python 2.7. Obtén Python 3 en la página de descarga de Python o con el administrador de paquetes de tu sistema operativo.
Para usuarios de Windows
Ver la documentación de Windows para obtener más información sobre cómo instalar Python.
Como colaborador, puedes ayudarnos a mantener la comunidad de Django abierta e inclusiva. Por favor, lee y sigue nuestro **Código de Conducta**_ https://www.djangoproject.com/conduct/.
Para seguir con este tutorial, necesitarás tener instalado Git para descargar la versión de desarrollo actual de Django y generar una rama para los cambios que realices.
To check whether or not you have Git installed, enter git into the command
line. If you get messages saying that this command could not be found, you’ll
have to download and install it, see Git’s download page.
Si no estás familiarizado con Git, siempre puedes 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 a Django es obtener una copia del código fuente. Primero, fork Django en GitHub. Luego, desde la línea de comandos, utiliza el comando cd para navegar hasta el directorio donde deseas que tu copia local de Django viva.
Descargar la biblioteca de código fuente de Django utilizando el siguiente comando:
$ git clone https://github.com/YourGitHubName/django.git
Conexión a baja velocidad?
Puedes agregar el argumento --depth 1 a git clone para saltarte la descarga de toda la historia de commits de Django, lo que reduce la transferencia de datos de ~250 MB a ~70 MB.
Ahora que tienes una copia local de Django, puedes instalarlo exactamente como si fuera un paquete más utilizando pip. La forma más conveniente de hacerlo es mediante un entorno virtual, que es una característica integrada en Python que te permite mantener un directorio separado de paquetes instalados para cada uno de tus proyectos, de modo que no se interfieran entre sí.
Es una buena idea mantener todos tus entornos virtuales en un lugar único, por ejemplo en .virtualenvs/ en tu directorio de inicio.
Crea un nuevo entorno virtual ejecutando:
$ python3 -m venv ~/.virtualenvs/djangodev
El camino es donde se guardará el nuevo entorno en tu computadora.
El último paso para configurar tu entorno virtual es activarlo:
$ source ~/.virtualenvs/djangodev/bin/activate
Si la orden source no está disponible, puedes intentar usar un punto en su lugar:
$ . ~/.virtualenvs/djangodev/bin/activate
Tienes que activar el entorno virtual cada vez que abras una nueva ventana de terminal.
Para usuarios de Windows
Para activar tu entorno virtual en Windows, ejecuta:
...\> %HOMEPATH%\.virtualenvs\djangodev\Scripts\activate.bat
El nombre del entorno virtual actualmente activado se muestra en la línea de comandos para ayudarte a mantener un seguimiento de cuál estás utilizando. Cualquier paquete que instales mediante pip mientras se muestra este nombre se instalará en ese entorno virtual, aislado de otros entornos y paquetes del sistema.
Puedes proceder a instalar la copia previamente clonada de Django:
$ python -m pip install -e /path/to/your/local/clone/django/
La versión instalada de Django ahora apunta a tu copia local al instalar en modo editable. Inmediatamente verás cualquier cambio que hagas en él, lo cual es de gran ayuda cuando estés probando tu primera contribución.
Cuando contribuyes a Django es muy importante que tus cambios de código no introduzcan errores en otras áreas de Django. Una forma de comprobar que Django sigue funcionando después de hacer los cambios es ejecutando el conjunto de pruebas de Django. Si todos los tests siguen pasando, entonces puedes estar razonablemente seguro de que tus cambios funcionan y no han roto otras partes de Django. Si nunca has ejecutado el conjunto de pruebas de Django antes, es una buena idea hacerlo una vez para familiarizarte con su salida.
Antes de ejecutar el conjunto de pruebas, ingresa al directorio Django tests/ utilizando el comando cd tests y instala las dependencias de prueba ejecutando:
$ python -m pip install -r requirements/py3.txt
Si encuentras un error durante la instalación, es posible que tu sistema esté faltando una dependencia para uno o más de los paquetes Python. Consulta la documentación del paquete que falló o busca en la web con el mensaje de error que encuentres.
Ahora estamos listos para ejecutar el conjunto de pruebas:
$ ./runtests.py
Ahora relájate. El conjunto de pruebas de Django tiene miles de pruebas y puede tardar al menos unos minutos en ejecutarse, dependiendo de la velocidad de tu computadora.
Mientras se ejecuta el conjunto de pruebas de Django, verás una secuencia de caracteres que representan el estado de cada prueba a medida que completa. E indica que se levantó un error durante una prueba y F indica que las afirmaciones de una prueba fallaron. Ambos son considerados como fallos en la prueba. Mientras tanto, x e s indican fallos esperados y pruebas omitidas, respectivamente. Los puntos indican pruebas que pasaron.
Las pruebas omitidas suelen deberse a bibliotecas externas faltantes necesarias para ejecutar la prueba; consulta Ejecutar todos los tests para obtener una lista de dependencias y asegúrate de instalar cualquier una relacionada con los cambios que estás haciendo (no necesitaremos ninguna para este tutorial). Algunas pruebas son específicas de un backend de base de datos particular y se omitirán si no estás probando con ese backend. SQLite es el backend de base de datos por defecto en las configuraciones predeterminadas. Para ejecutar las pruebas utilizando un backend diferente, consulta Usando otro módulo settings.
Una vez que las pruebas completen, deberías recibir un mensaje informándote si el conjunto de pruebas pasó o falló. Dado que aún no has realizado cambios en el código de Django, debería pasar todo el conjunto de pruebas. Si obtienes fallos o errores asegúrate de haber seguido todos los pasos anteriores correctamente. Consulta Ejecutar las pruebas unitarias para obtener más información.
Ten en cuenta que la rama «main» más reciente de Django no siempre es estable. Al desarrollar contra «main», puedes verificar Django’s continuous integration builds para determinar si los fallos son específicos de tu máquina o también están presentes en las compilaciones oficiales de Django. Si haces clic para ver una compilación particular, puedes ver la «Matriz de configuración» que muestra los fallos desglosados por versión de Python y backend de base de datos.
Nota
Para este tutorial y el ticket con el que estamos trabajando, probar contra SQLite es suficiente, sin embargo, es posible (y a veces necesario) ejectar las pruebas utilizando un backend diferente. Al realizar cambios en la interfaz de usuario, necesitarás ejectar las pruebas de Selenium.
Para este tutorial, trabajaremos en un «ticket aceptado falso» como estudio de caso. Aquí están los detalles imaginarios:
Ticket #99999 – Permitir hacer tostada
Django debería proporcionar una función django.shortcuts.make_toast() que devuelve 'tostada'.
Ahora implementaremos esta característica y los tests asociados.
Antes de hacer cualquier cambio, crea una nueva rama para el ticket:
$ git checkout -b ticket_99999
Puedes elegir cualquier nombre que desees para la rama, «ticket_99999» es un ejemplo. Todos los cambios realizados en esta rama serán específicos del ticket y no afectarán la copia principal de código que clonamos anteriormente.
En la mayoría de los casos, para que una contribución sea aceptada en Django tiene que incluir tests. Para las contribuciones de corrección de errores, esto significa escribir un test de regresión para asegurarse de que el error no se reintroduzca en Django más adelante. Un test de regresión debe escribirse de tal manera que fallará mientras el error aún exista y pase una vez que el error haya sido corregido. Para las contribuciones que contienen nuevas características, necesitarás incluir tests que aseguren que las nuevas características estén funcionando correctamente. También deben fallar cuando la nueva característica no está presente, y luego pasar una vez que se ha implementado.
Una buena forma de hacer esto es escribir tus nuevos tests primero, antes de hacer cualquier cambio en el código. Este estilo de desarrollo se llama desarrollo dirigido por pruebas y puede aplicarse tanto a proyectos enteros como a cambios individuales. Después de escribir tus tests, entonces los ejecutas para asegurarte de que efectivamente fallan (ya que no has corregido ese error o agregado esa característica aún). Si tus nuevos tests no fallan, necesitarás arreglarlos para que sí lo hagan. Después de todo, un test de regresión que pasa sin importar si existe un error no es muy útil a la hora de prevenir que el error vuelva a ocurrir más adelante.
Ahora para nuestro ejemplo práctico.
Para resolver este ticket, agregaremos una función make_toast() al módulo django.shortcuts. Primero vamos a escribir un test que intenta utilizar la función y verifica que su salida se ve correcta.
Navega hasta el directorio tests/shortcuts/ de Django y crea un nuevo archivo test_make_toast.py. Agrega el siguiente código:
from django.shortcuts import make_toast
from django.test import SimpleTestCase
class MakeToastTests(SimpleTestCase):
def test_make_toast(self):
self.assertEqual(make_toast(), "toast")
Este test verifica que la función make_toast() devuelve 'toast'.
Pero esto del testing parece un poco difícil…
Si nunca has tenido que manejar tests antes, pueden parecer un poco difíciles de escribir a primera vista. Por suerte, el testing es un muy gran tema en la programación informática, por lo que hay mucha información disponible:
Una buena primera mirada sobre cómo escribir tests para Django se puede encontrar en la documentación sobre Escribir y ejecutar pruebas.
Dive Into Python (un libro en línea gratuito para desarrolladores de Python principiantes) incluye una gran introducción a los pruebas unitarias.
Después de leer eso, si quieres algo un poco más sustancioso para meterte en el tema, siempre hay la documentación del módulo unittest de Python.
Dado que aún no hemos realizado ninguna modificación a django.shortcuts todavía, nuestro test debería fallar. Vamos a ejecutar todos los tests en el directorio shortcuts para asegurarnos de que eso es realmente lo que sucede. Ejecuta:
$ ./runtests.py shortcuts
Si los tests se ejecutaron correctamente, deberías ver una sola falla correspondiente al método de test que agregamos, con este error:
ImportError: cannot import name 'make_toast' from 'django.shortcuts'
Si todos los tests pasaron, entonces querrás asegurarte de que agregaste el nuevo test mostrado anteriormente a la carpeta y archivo correctos.
A continuación, agregaríamos la función make_toast().
Navega al directorio django/ y abre el archivo shortcuts.py. En la parte inferior, agrega:
def make_toast():
return "toast"
Ahora necesitamos asegurarnos de que el test que escribimos anteriormente pase, para ver si el código que agregamos está funcionando correctamente. De nuevo, navega al directorio de tests Django y ejecuta:
$ ./runtests.py shortcuts
Todo debería pasar. Si no es así, asegúrate de haber agregado la función a la carpeta correcta.
Una vez que hayas verificado que tus cambios y pruebas funcionan correctamente, es una buena idea ejecutar la suite de pruebas completa de Django para verificar que tu cambio no ha introducido ningún error en otras áreas de Django. Si bien pasar con éxito toda la suite de pruebas no garantiza que tu código esté libre de errores, ayuda a identificar muchos errores y regresiones que podrían pasar desapercibidas de otra manera.
Para ejecutar toda la suite de pruebas de Django, cd en el directorio de Django tests/ y ejecuta:
$ ./runtests.py
Esta es una nueva característica, por lo que debe ser documentada. Abre el archivo docs/topics/http/shortcuts.txt y agrega lo siguiente al final del archivo:
``make_toast()``
================
.. function:: make_toast()
.. versionadded:: 2.2
Returns ``'toast'``.
Dado que esta nueva característica estará en la próxima versión de Django, también se agrega a las notas de lanzamiento para la siguiente versión de Django. Abre las notas de lanzamiento para la última versión en docs/releases/, lo cual en el momento de escribir esto es 2.2.txt. Agrega una nota bajo el encabezado «Características menores»:
:mod:`django.shortcuts`
~~~~~~~~~~~~~~~~~~~~~~~
* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.
Para obtener más información sobre la escritura de documentación, incluyendo una explicación de qué es todo el versionadded, vea Escribir documentación. Esa página también incluye una explicación de cómo construir una copia de la documentación localmente, para que puedas visualizar el HTML que se generará.
Ahora es hora de revisar los cambios realizados en la rama. Para preparar todos los cambios para su commit, ejecuta:
$ git add --all
Muestra las diferencias entre tu copia actual de Django (con tus cambios) y la revisión que inicialmente descartaste más temprano en el tutorial con:
$ git diff --cached
Usa las teclas de flecha para moverte hacia arriba y hacia abajo.
diff --git a/django/shortcuts.py b/django/shortcuts.py
index 7ab1df0e9d..8dde9e28d9 100644
--- a/django/shortcuts.py
+++ b/django/shortcuts.py
@@ -156,3 +156,7 @@ def resolve_url(to, *args, **kwargs):
# Finally, fall back and assume it's a URL
return to
+
+
+def make_toast():
+ return 'toast'
diff --git a/docs/releases/2.2.txt b/docs/releases/2.2.txt
index 7d85d30c4a..81518187b3 100644
--- a/docs/releases/2.2.txt
+++ b/docs/releases/2.2.txt
@@ -40,6 +40,11 @@ database constraints. Constraints are added to models using the
Minor features
--------------
+:mod:`django.shortcuts`
+~~~~~~~~~~~~~~~~~~~~~~~
+
+* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.
+
:mod:`django.contrib.admin`
~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt
index 7b3a3a2c00..711bf6bb6d 100644
--- a/docs/topics/http/shortcuts.txt
+++ b/docs/topics/http/shortcuts.txt
@@ -271,3 +271,12 @@ This example is equivalent to::
my_objects = list(MyModel.objects.filter(published=True))
if not my_objects:
raise Http404("No MyModel matches the given query.")
+
+``make_toast()``
+================
+
+.. function:: make_toast()
+
+.. versionadded:: 2.2
+
+Returns ``'toast'``.
diff --git a/tests/shortcuts/test_make_toast.py b/tests/shortcuts/test_make_toast.py
new file mode 100644
index 0000000000..6f4c627b6e
--- /dev/null
+++ b/tests/shortcuts/test_make_toast.py
@@ -0,0 +1,7 @@
+from django.shortcuts import make_toast
+from django.test import SimpleTestCase
+
+
+class MakeToastTests(SimpleTestCase):
+ def test_make_toast(self):
+ self.assertEqual(make_toast(), 'toast')
Cuando hayas terminado de visualizar los cambios, presiona la tecla q para regresar a la línea de comandos. Si el diff parecía correcto, es hora de realizar un commit de los cambios.
Para realizar el commit de los cambios:
$ git commit
Esto abre un editor de texto para escribir el mensaje del commit. Sigue las directrices del mensaje del commit y escribe un mensaje como:
Fixed #99999 -- Added a shortcut function to make toast.
Después de realizar el commit de los cambios, envíalo a tu fork en GitHub (sustituye «ticket_99999» con el nombre de tu rama si es diferente):
$ git push origin ticket_99999
Puedes crear una solicitud de extracción visitando la página GitHub de Django. Verás tu rama bajo «Ramas recientemente empujadas». Haz clic en «Comparar y solicitar extracción» junto a ella.
Por favor, no lo hagas para este tutorial, pero en la siguiente página que muestra una previsualización de los cambios, deberías hacer clic en «Crear solicitud de extracción».
¡Enhorabuena! Has aprendido a crear una solicitud de extracción para Django. Detalles de técnicas más avanzadas que puedas necesitar se encuentran en Trabajando con Git y GitHub.
Ahora puedes poner en práctica esas habilidades ayudando a mejorar el código base de Django.
Antes de que te sumergas demasiado en la contribución a Django, hay un poco más de información sobre la contribución que probablemente debieras revisar:
Debes asegurarte de leer la documentación de Django sobre reclamar tickets y enviar solicitudes de cambio. Cubre el etiqueta de Trac, cómo reclamar tickets para ti mismo, estilo de codificación esperado (tanto para código como para documentos), y muchos otros detalles importantes.
Los contribuyentes por primera vez también deben leer la documentación de Django sobre contribución para contribuyentes por primera vez. Tiene mucha buena consejos para aquellos que son nuevos en ayudar con Django.
Después de eso, si todavía estás hambriento de más información sobre la contribución, siempre puedes navegar a través del resto de documentación de Django sobre contribución. Contiene una tonelada de información útil y debería ser tu primera fuente para responder cualquier pregunta que puedas tener.
Una vez que hayas revisado esa información, estarás listo para ir a buscar un ticket propio para contribuir. Presta especial atención a los tickets con el criterio de «easy pickings». Estos tickets son a menudo mucho más simples en naturaleza y son ideales para contribuyentes por primera vez. Una vez que estés familiarizado con la contribución a Django, puedes empezar a trabajar en tickets más difíciles y complicados.
Si solo quieres empezar ya (y nadie te culparía!), prueba mirando la lista de tickets fáciles sin rama y los tickets fáciles que tienen ramas que necesitan mejora. Si estás familiarizado con escribir pruebas, también puedes mirar la lista de tickets fáciles que necesitan pruebas. Recuerda seguir las directrices sobre reclamar tickets que se mencionan en el enlace a la documentación de Django sobre reclamar tickets y enviar ramas.
Después de que un ticket tenga una rama, necesita ser revisado por un segundo conjunto de ojos. Después de enviar una solicitud de extracción, actualiza la información del ticket estableciendo las banderas en el ticket para decir «tiene parche», «no necesita pruebas», etc., para que otros puedan encontrarlo para su revisión. Contribuir no significa necesariamente siempre escribir código desde cero. Revisar solicitudes de extracción abiertas también es una contribución muy útil. Consulta Triage de tickets para obtener más detalles.
may 31, 2026