Siempre estamos agradecidos por las contribuciones al código de Django. De hecho, los informes de errores con contribuciones asociadas se arreglarán mucho más rápido que aquellos sin solución.
Si estás corrigiendo un problema realmente trivial, por ejemplo cambiando una palabra en la documentación, el método preferido para proporcionar la parche es mediante solicitudes de pull de GitHub sin una tarjeta Trac.
Consulte el trabajando-con-git para obtener más detalles sobre cómo utilizar solicitudes de pull.
En un proyecto de código abierto con cientos de contribuyentes en todo el mundo, es importante gestionar la comunicación de manera eficiente para que no se dupliquen los trabajos y los contribuyentes puedan ser tan efectivos como sea posible.
Por lo tanto, nuestra política es que los contribuyentes «reclamen» las tickets para permitir a otros desarrolladores saber que un determinado bug o característica está siendo trabajada.
Si has identificado una contribución que deseas hacer y tienes la capacidad de arreglarla (según se mide por tu habilidad en programación, conocimiento de Django internals y disponibilidad de tiempo), reclámala siguiendo estos pasos:
Inicia sesión utilizando tu cuenta de GitHub o crea una cuenta en nuestro sistema de tickets. Si tienes una cuenta pero has olvidado tu contraseña, puedes restablecerla utilizando la página de _`restauración de contraseña`_.
Si no existe aún un ticket para este problema, crea uno en nuestro tracker de tickets`_. Recuerda que las propuestas para nuevas características deben seguir el :ref:`proceso para sugerir nuevas características <requesting-features>.
Si ya existe un ticket para este problema, asegúrate de que nadie más lo haya reclamado. Para hacer esto, mira la sección «Propietario» del ticket. Si está asignado a «nadie», entonces está disponible para ser reclamado. De lo contrario, alguien más puede estar trabajando en este ticket. O encuentra otro bug/funcionalidad para trabajar o contacta al desarrollador que trabaja en el ticket para ofrecer tu ayuda. Si un ticket ha sido asignado durante semanas o meses sin actividad alguna, probablemente es seguro reasignarlo a ti mismo.
Inicia sesión en tu cuenta, si no lo has hecho ya, haciendo clic en «Login de GitHub» o «Login DjangoProject» en la parte superior izquierda de la página del ticket. Una vez iniciado sesión, puedes hacer clic en el botón «Modificar Ticket» cerca de la parte inferior de la página.
Reclama el ticket haciendo clic en el botón radio «asignar a» en la sección «Acción». Tu nombre de usuario estará rellenado por defecto en el cuadro de texto.
Finalmente haz clic en el botón «Enviar cambios» en la parte inferior para guardar los cambios.
Nota
La fundación del software Django solicita que cualquier persona contribuyendo con más de un cambio trivial, a Django firme y envíe un _`Acuerdo de Licencia de Contribución`_, esto garantiza que la Fundación del Software Django tenga una licencia clara para todas las contribuciones, permitiendo una licencia clara para todos los usuarios.
Una vez que hayas reclamado un ticket, tienes la responsabilidad de trabajar en ese ticket con una cierta urgencia. Si no tienes tiempo para trabajar en él, ya sea deshazte de la reclamación o no reclames el ticket en primer lugar.
Si no se ve ningún signo de progreso en un ticket reclamado durante una semana o dos, otro desarrollador puede preguntarte que renuncies a la reclamación del ticket para que ya no lo monopolices y alguien más pueda reclamarlo.
Si has reclamado un ticket y está tomando mucho tiempo (días o semanas) para codificar, mantén a todos informados publicando comentarios en el ticket. Si no proporcionas actualizaciones regulares y no respondes a una solicitud de informe de progreso, tu reclamación del ticket puede ser revocada.
Como siempre, más comunicación es mejor que menos comunicación.
Ir paso a paso por el proceso de reclamar tickets es un exceso en algunos casos.
En el caso de cambios pequeños, como errores de ortografía en la documentación o pequeños bugs que solo tomarán unos minutos para arreglar, no necesitas saltar por los trastos de reclamar tickets. Envía tus cambios directamente y ya está hecho!
Es siempre aceptable, independientemente de si alguien lo ha reclamado o no, enlazar propuestas a un ticket si tienes las modificaciones listas.
Asegúrate de que cualquier contribución que realices cumpla al menos con los siguientes requisitos:
El código necesario para solucionar un problema o agregar una función es parte fundamental de la solución, pero no es el único. Una buena corrección también debe incluir un prueba de regresión para validar el comportamiento que se ha corregido y prevenir que el problema vuelva a surgir. Además, si algunos tickets son relevantes para el código que has escrito, menciona los números de ticket en algún comentario en la prueba para que puedas rastrear fácilmente las discusiones relevantes después de que tu parche se comunique y los tickets se cierren.
Si el código agrega una nueva función o modifica el comportamiento de una función existente, la modificación también debe contener documentación.
Cuando creas que tu trabajo está listo para ser revisado, envía una solicitud de extracción en GitHub. Si no puedes enviar una solicitud de extracción por alguna razón, también puedes utilizar parches en Trac. Cuando utilices este estilo, sigue estas directrices.
Envía parches en el formato devuelto por la orden git diff.
Adjunta parches a un ticket en el tracker de tickets, utilizando el botón «adjuntar archivo». Por favor, no coloques el parche en la descripción del ticket o comentario a menos que sea un parche de una sola línea.
Nombra el archivo del parche con una extensión .diff; esto permitirá al tracker de tickets aplicar resaltado de sintaxis correcto, lo cual es muy útil.
Independientemente del método que utilices para enviar tu trabajo, sigue estos pasos.
Asegúrate de que tu código cumpla con los requisitos en nuestra lista de verificación de contribución.
Verifica el cuadro «Tiene parche» en el ticket y asegúrate de que no estén seleccionados los cuadros «Necesita documentación», «Necesita pruebas» y «Parche necesita mejoras». Esto hace que el ticket aparezca en la cola «Parches necesarios para revisión» del panel de desarrollo.
Una discusión más amplia de la comunidad es necesaria cuando una parche introduce nueva funcionalidad de Django y hace alguna clase de decisión de diseño. Esto es especialmente importante si el enfoque implica un deprecación o introduce cambios que rompen.
Los siguientes son diferentes enfoques para obtener retroalimentación de la comunidad.
Si tienes una idea para una nueva característica, por favor crea un nuevo proyecto (o únete a una discusión existente) siguiendo el proceso para sugerir nuevas características. Debes explicar la necesidad del cambio, entrar en detalles sobre el enfoque y discutir alternativas.
Puedes proponer un cambio (que no sea una idea de nueva característica) en el Django Forum. Debes explicar la necesidad del cambio, entrar en detalles sobre el enfoque y discutir alternativas.
Por favor incluye un enlace a tales discusiones en tus contribuciones.
Django no acepta características experimentales. Todas las características deben seguir nuestra política de deprecación. Por lo tanto, puede llevar meses o años para que Django itere en el diseño de la API pública.
Si necesitas retroalimentación del usuario sobre una interfaz pública, es mejor crear un paquete de terceros primero. Puedes iterar en la API pública mucho más rápido, mientras también validas la necesidad de la característica.
Once this package becomes stable and there are clear benefits of incorporating aspects into Django core, the next step is to propose its inclusion by following the proceso para sugerir nuevas características.
Similar a los PEPs de Python, Django tiene Propuestas de Mejora de Django o DEPs. Una DEP es un documento de diseño que proporciona información a la comunidad de Django, o describe una nueva característica o proceso para Django. Proporcionan especificaciones técnicas concisas de características, junto con sus razones. Las DEPs también son el mecanismo principal para proponer y recopilar la entrada de la comunidad sobre nuevas características importantes.
Antes de considerar escribir una DEP, se recomienda abrir primero una discusión siguiendo el proceso para sugerir nuevas características. Esto permite a la comunidad proporcionar retroalimentación y ayuda a refinar la propuesta. Una vez que la DEP esté lista, el Consejo Directivo vota sobre si aceptarla.
Algunos ejemplos de DEPs que han sido aprobados y completamente implementados:
Hay un par de razones por las que el código en Django podría estar deprecado:
Si una característica ha sido mejorada o modificada de manera incompatible con el pasado, la antigua característica o comportamiento se depreciará.
A veces Django incluye un backport de una biblioteca de Python que no está incluida en una versión de Python que Django actualmente admite. Cuando Django ya no necesita admitir la versión más antigua de Python que no incluye la biblioteca, la biblioteca se depreciará en Django.
Como describe la política de deprecación , la primera versión de Django que deprecia una característica (A.B) debería lanzar un RemovedInDjangoXXWarning (donde XX es la versión de Django donde la característica se eliminará) cuando la característica depreciada se invoque. Asumiendo que tenemos buena cobertura de pruebas, estos avisos se convierten en errores cuando se ejecuta el conjunto de pruebas con los avisos habilitados: python -Wa runtests.py . Por lo tanto, al agregar un RemovedInDjangoXXWarning debes eliminar o silenciar cualquier advertencia generada al ejecutar las pruebas.
El primer paso es eliminar cualquier uso de la depreciación del comportamiento por parte de Django mismo. A continuación, puedes silenciar los avisos en las pruebas que realmente prueban el comportamiento depreciado utilizando el decorador ignore_warnings , ya sea a nivel de prueba o clase:
En una prueba particular:
from django.test import ignore_warnings
from django.utils.deprecation import RemovedInDjangoXXWarning
@ignore_warnings(category=RemovedInDjangoXXWarning)
def test_foo(self): ...
Para un caso de prueba completo:
from django.test import ignore_warnings
from django.utils.deprecation import RemovedInDjangoXXWarning
@ignore_warnings(category=RemovedInDjangoXXWarning)
class MyDeprecatedTests(unittest.TestCase): ...
También debes agregar una prueba para el aviso de depreciación:
from django.utils.deprecation import RemovedInDjangoXXWarning
def test_foo_deprecation_warning(self):
msg = "Expected deprecation message"
with self.assertWarnsMessage(RemovedInDjangoXXWarning, msg) as ctx:
# invoke deprecated behavior
...
self.assertEqual(ctx.filename, __file__)
Es importante incluir un comentario RemovedInDjangoXXWarning sobre el código que no tiene referencia a advertencia, pero necesitará ser cambiado o eliminado cuando la depreciación termine. Esto podría incluir ganchos que se han agregado para mantener el comportamiento anterior, o elementos independientes que son innecesarios o no utilizados cuando la depreciación termine. Por ejemplo:
import warnings
from django.utils.deprecation import RemovedInDjangoXXWarning
# RemovedInDjangoXXWarning.
def old_private_helper():
# Helper function that is only used in foo().
pass
def foo():
warnings.warn(
"foo() is deprecated.",
category=RemovedInDjangoXXWarning,
stacklevel=2,
)
old_private_helper()
...
Finalmente, hay algunas actualizaciones en la documentación de Django para hacer:
Si la característica existente está documentada, marcala como depreciada en la documentación utilizando la anotación .. deprecated:: A.B . Incluye una descripción breve y un recordatorio sobre el camino de mejora si corresponde.
Add a description of the deprecated behavior, and the upgrade path if
applicable, to the current release notes (docs/releases/A.B.txt) under
the «Features deprecated in A.B» heading.
Agregar una entrada en la cronología de desprecios (docs/internals/deprecation.txt) bajo la versión correspondiente describiendo qué código se eliminará.
Una vez que hayas completado estos pasos, habrás terminado con el desprecio. En cada lanzamiento de características, se eliminan todas las advertencias RemovedInDjangoXXWarnings que coincidan con la nueva versión.
Es importante probar los cambios locales utilizando un proyecto Django. Esto permite asegurarse de que los cambios se comporten como se espera en un entorno real, especialmente para características de usuario como plantillas, formularios o el administrador.
Para hacer esto:
Crear un entorno virtual y instalar la copia clonada de Django en modo editable.
Configurar un proyecto Django fuera del árbol de fuentes (puedes utilizar el primera parte del tutorial para obtener orientación).
Con esta configuración, cualquier cambio realizado en la copia de Django tendrá efecto inmediato en el proyecto de prueba, permitiendo pruebas manuales de contribuciones contra una aplicación nueva o existente.
Para información sobre contribuciones de JavaScript, consulta la documentación Parches de JavaScript.
Los parches que buscan mejorar el rendimiento deben proporcionar benchmarks que muestren el impacto antes y después del parche y compartir los comandos para que los revisores puedan reproducirlos.
django-asv¶django-asv monitorea el rendimiento del código Django con el tiempo. Estos benchmarks se pueden ejecutar en una solicitud de extracción etiquetando la solicitud con benchmark. Se alienta mucho a agregar a estos benchmarks.
Utiliza esta lista de comprobación para revisar una solicitud de extracción. Si esta contribución no sería considerada trivial, asegúrate primero de que tiene un ticket aceptado antes de proceder con la revisión.
Si la solicitud de extracción pasa todos los criterios siguientes y no es tuya, por favor establece el «Triage Stage» en el ticket Trac correspondiente a «Ready for checkin». Si has dejado comentarios para mejorar en la solicitud de extracción, por favor marca las banderas adecuadas en el ticket Trac según los resultados de tu revisión: «Parche necesita mejoras», «Necesita documentación» y/o «Necesita pruebas». A medida que el tiempo y el interés lo permitan, los integradores realizan revisiones finales de los tickets «Ready for checkin» y cometerán los cambios o volverán a marcarlo como «Aceptado» si se necesita más trabajo.
Si estás buscando convertirte en miembro del equipo de triage & review, hacer revisiones exhaustivas de contribuciones es una excelente manera de ganar confianza.
Buscando un parche para revisar? Consulta la sección «Parches que necesitan revisión» del Django Development Dashboard.
¿Buscas que se revise tu solicitud de extracción? Asegúrate de que las banderas Trac en la tarjeta estén configuradas para que la tarjeta aparezca en esa cola.
¿La documentación se compila sin errores (make html, o make.bat html en Windows, desde el directorio docs)?
¿La documentación sigue las directrices de estilo de escritura en Escribir documentación?
¿Hay algún error de ortografía (spelling errors <documentation-spelling-check>)?
¿Hay una prueba de regresión adecuada (la prueba debe fallar antes de aplicar la corrección)?
Si es un bug que cumple con las políticas de backport a la versión estable de Django, ¿hay un anuncio de lanzamiento en docs/releases/A.B.C.txt? Las correcciones de bugs que solo se aplicarán a la rama principal no necesitan un anuncio de lanzamiento.
¿Hay pruebas para «ejercitar» todo el nuevo código?
¿Hay un anuncio de lanzamiento en docs/releases/A.B.txt?
Hay documentación para la característica y está anotada adecuadamente con .. versionadded:: A.B o .. versionchanged:: A.B?
Consulte el guía de deshabilitar una característica.
¿Conforma la norma de codificación a nuestras directrices? ¿Hay errores de black, blacken-docs, flake8, isort o zizmor? Puedes instalar los hooks pre-commit para capturar automáticamente estos errores.
Si el cambio es incompatible con versiones anteriores de cualquier manera, ¿hay una nota en las notas de lanzamiento (docs/releases/A.B.txt)?
¿Está pasando la suite de pruebas de Django?
Si el cambio afecta la interfaz administrativa de Django o el HTML renderizado, ¿se ha realizado pruebas de accesibilidad?
¿Es la solicitud de extracción un solo commit compactado con un mensaje que sigue nuestro formato de mensaje de commit?
¿Eres el autor del parche y un nuevo contribuyente? Por favor, añade tu nombre a el archivo AUTHORS y envía un Contributor License Agreement.
Does this have an accepted ticket on Trac? Toda contribución requiere un ticket a menos que el cambio se considere trivial <trivial-change>.
may 31, 2026