Esta sección está dirigida a los merge y a cualquier persona interesada en saber cómo se comite el código en Django. Si eres miembro de la comunidad que quiere contribuir código a Django, mira Trabajando con Git y GitHub en lugar de eso.
Since Django está alojado en GitHub, los parches se proporcionan en forma de solicitudes de extracción.
Al enviar una solicitud de extracción, asegúrate de que cada commit individual cumpla con las directrices de commit descritas a continuación. Los contribuyentes deben proporcionar las mejores solicitudes de extracción posibles. En la práctica, los merge - quienes probablemente sean más familiarizados con las directrices de commit - pueden decidir llevar un commit hasta el estándar ellos mismos.
Puede que desee probar la solicitud de extracción con Jenkins o GitHub actions utilizando uno de los constructores de solicitudes de extracción que no se ejecutan automáticamente, como Oracle o Selenium. Consulta la página wiki de CI para obtener instrucciones.
Si te encuentras revisando solicitudes de extracción localmente con frecuencia, esta alias git será útil:
[alias]
pr = !sh -c \"git fetch upstream pull/${1}/head:pr/${1} && git checkout pr/${1}\"
Añádelo a tu ~/.gitconfig, y establece upstream en ser django/django. Luego puedes ejecutar git pr #### para verificar la solicitud de extracción correspondiente.
En este punto, puedes trabajar en el código. Utiliza git rebase -i y git commit --amend para asegurarte de que los commits tengan el nivel de calidad esperado. Una vez estés listo:
$ # Pull in the latest changes from main.
$ git checkout main
$ git pull upstream main
$ # Rebase the pull request on main.
$ git checkout pr/####
$ git rebase main
$ git checkout main
$ # Merge the work as "fast-forward" to main to avoid a merge commit.
$ # (in practice, you can omit "--ff-only" since you just rebased)
$ git merge --ff-only pr/XXXX
$ # If you're not sure if you did things correctly, check that only the
$ # changes you expect will be pushed to upstream.
$ git push --dry-run upstream main
$ # Push!
$ git push upstream main
$ # Delete the pull request branch.
$ git branch -d pr/xxxx
Haz un push forzado a la rama después de rebasar sobre main pero antes de fusionar y empujar a upstream. Esto permite que las huellas de commit en main y la rama coincidan lo cual cierra automáticamente la solicitud de extracción.
Si una solicitud de extracción no necesita ser fusionada como múltiples commits, puedes utilizar el botón «Squash and merge» de GitHub en la web. Edita el mensaje de commit según sea necesario para que se ajuste a las directrices:ref:las directrices <committing-guidelines> y elimina el número de solicitud de extracción que se agrega automáticamente al primer línea del mensaje.
Al reescribir la historia de commits de una solicitud de extracción, el objetivo es hacer que la historia de commits de Django sea lo más usable posible:
Si un parche contiene commits de ida y vuelta, entonces reescribe esos en uno. Por ejemplo, si un commit agrega algún código y un segundo commit corrige problemas estilísticos introducidos en el primer commit, esos commits deben ser aplastados antes de fusionar.
Los textos traducidos son:
Ten cuidado con las fusiones de ramas de origen en las solicitudes de pull.
Los tests deben pasar y los docs deben construirse después de cada commit. Ninguno de los tests ni los docs deberían emitir advertencias.
Las parches triviales y pequeños suelen ser mejor hacerlos en un solo commit. El trabajo medio a grande puede dividirse en múltiples commits si tiene sentido.
La práctica prevalece sobre la pureza, por lo que es hasta cada integrador decidir cuánta manipulación de la historia hacer para una solicitud de pull. Los puntos principales son involucrar a la comunidad, realizar trabajo y tener una historia de commits usable.
Además, por favor sigue las siguientes directrices cuando comites código en el repositorio Git de Django:
Nunca cambies la historia publicada de las ramas django/django mediante empujones forzados. Si absolutamente debes hacerlo (por ejemplo, por razones de seguridad), discute primero la situación con el equipo.
Para cualquier cambio medio-grande, donde «medio-grande» es según tu criterio, por favor habla de ello en el **Foro de Django**_ antes de realizar el cambio.
Si hablas de algo y nadie responde, no te tomes eso como que tu idea es genial y debe implementarse inmediatamente porque nadie la ha cuestionado. A todos no siempre les queda tiempo para leer las discusiones en ese momento, por lo que puede tener que esperar unos días antes de obtener una respuesta.
Write detailed commit messages in the past tense, not present tense.
Bien: «Se corrigió el bug Unicode en la API RSS.»
Mal: «Corrige el bug Unicode en la API RSS.»
Mal: «Corrigiendo el bug Unicode en la API RSS.»
El mensaje de commit debería estar en líneas de 72 caracteres máximo. Debe haber una línea de título, separada por una línea en blanco y luego párrafos de líneas de 72 caracteres. Los límites son suaves. Para la línea de título, ser más corta es mejor. En el cuerpo del mensaje de commit, más detalles son mejores que menos:
Fixed #18307 -- Added git workflow guidelines.
Refactored the Django's documentation to remove mentions of SVN
specific tasks. Added guidelines of how to use Git, GitHub, and
how to use pull request together with Trac instead.
Credita a los contribuyentes en el mensaje de commit: «Gracias A por el informe y B por la revisión.» Utiliza Co-Authored-By de git según corresponda.
Para commits a una rama, antepón al mensaje de commit el nombre de la rama. Por ejemplo: «[1.4.x] Se corrigió #xxxxx – Se agregó soporte para lectura de mentes.»
Limita los commits al cambio más granular que tenga sentido. Esto significa utilizar commits pequeños y frecuentes en lugar de commits grandes e infrecuentes. Por ejemplo, si la implementación de la característica X requiere un pequeño cambio a la biblioteca Y, primero comita el cambio a la biblioteca Y, luego comita la característica X en un commit separado. Esto va una gran distancia en ayudar a todos a seguir tus cambios.
Separa los arreglos de bugs de las modificaciones de características. Los arreglos de bugs pueden necesitar ser reintroducidos en la rama estable, según la política de Versiones soportadas.
Si tu commit cierra un ticket en el tracker de tickets Django , comienza tu mensaje de commit con el texto «Se corrigió #xxxxx», donde «xxxxx» es el número del ticket que tu commit arregla. Ejemplo: «Se corrigió #123 – Se agregó la característica whizbang.». Hemos configurado Trac para que cualquier mensaje de commit en ese formato automáticamente cierre el ticket referenciado y poste un comentario con el mensaje de commit completo.
Los textos traducidos son:
Nota
Ten en cuenta que la integración con Trac no sabe nada sobre solicitudes de extracción. Por lo tanto, si intentas cerrar una solicitud de extracción con la frase «cierra #400» en tu mensaje de commit, GitHub cerrará la solicitud de extracción, pero el plugin de Trac no cerrará el mismo número de ticket en Trac.
Si tu commit hace referencia a un ticket en el tracker de tickets de Django pero no cierra el ticket, incluye la frase «Refs #xxxxx», donde «xxxxx» es el número del ticket que se está haciendo referencia. Esto publicará automáticamente un comentario en el ticket correspondiente.
Escribe mensajes de commit para backports utilizando este patrón:
[<Django version>] Fixed <ticket> -- <description>
Backport of <revision> from <branch>.
Por ejemplo:
[1.3.x] Fixed #17028 -- Changed diveintopython.org -> diveintopython.net.
Backport of 80c0cbf1c97047daed2c5b41b296bbc56fe1d7e3 from main.
Hay un script en la wiki para automatizar esto.
Si el commit corrige una regresión, incluye esto en el mensaje de commit:
Regression in 6ecccad711b52f9273b1acb07a57d3f806e93928.
(usa el hash del commit donde se introdujo la regresión).
Nadie es perfecto; los errores serán cometidos.
Pero trata muy en serio de asegurarte de que los errores no sucedan. Aunque tengamos una política de reversiones, esto no relaja tu responsabilidad de aspirar a la mayor calidad posible. En realidad: revisa doblemente tu trabajo o haz que otro mergeador lo revise antes de que lo comitas en primer lugar.
Cuando se descubre un commit equivocado, por favor sigue estas directrices:
Si es posible, pide al autor original que reversione su propio commit.
No reversiones cambios de otro autor sin permiso del autor original.
Utiliza git revert – esto hará un commit inverso, pero el commit original seguirá siendo parte de la historia de commits.
Si no se puede llegar al autor original (dentro de un plazo razonable – un día o así) y el problema es grave – fallo que causa caída del sistema, fallas importantes en las pruebas, etc. – entonces pide objeciones en el Django Forum y reversiona si no hay ninguna.
Si el problema es pequeño (un commit de una característica después de la congelación de características, por ejemplo), espera a que se resuelva.
Si hay un desacuerdo entre el mergeador y quien va a reversionar entonces trata de resolverlo en el Django Forum . Si no se puede llegar a un acuerdo entonces debe someterse a votación.
Si el commit introdujo una vulnerabilidad de seguridad confirmada y declarada, entonces el commit puede ser reversionado inmediatamente sin permiso de nadie.
El mantenedor del rama de liberación puede deshacer commits en la rama de liberación sin permiso si el commit rompe la rama de liberación.
Si accidentalmente pusiste una rama de tema en django/django, borradla. Por ejemplo, si hiciste: git push upstream feature_antigravity, haz un empuje inverso: git push upstream :feature_antigravity.
may 31, 2026