Los parches son la mejor manera de proporcionar una corrección de error o de proponer mejoras a Symfony2.
Antes de trabajar en Symfony2, configura un entorno amigable con el siguiente software:
Configura la información de usuario con tu nombre real y una dirección de correo electrónico operativa:
$ git config --global user.name "Tu nombre"
$ git config --global user.email tu@ejemplo.com
Truco
Si eres nuevo en Git, es muy recomendable que leas el excelente libro ProGit, que además es gratis.
Truco
Si tu IDE crea los archivos de configuración dentro del directorio del proyecto, puedes usar el archivo global .gitignore (para todos los proyectos) o el archivo .git/info/exclude (por proyecto) para descartarlos. Consulta la documentación de Github.
Truco
Usuarios de Windows: al instalar Git, se te preguntará qué hacer con los finales de línea y te sugiere reemplazar todos los LF por CRLF. ¡Esta es la opción incorrecta si deseas contribuir con Symfony! Seleccionar el método tal cual es tu mejor opción, puesto que Git convertirá tus saltos de línea a los del repositorio. Si ya has instalado Git, puedes comprobar el valor de esta opción escribiendo:
$ git config core.autocrlf
Esto devolverá o bien «false», «input» o «true», «true» y «false» son valores incorrectos. Para fijarlo a otro valor, escribe:
$ git config --global core.autocrlf input
Sustituye --global por --local si lo quieres fijar únicamente para el repositorio activo.
Obtén el código fuente de Symfony2:
$ git clone git@github.com:NOMBREUSUARIO/symfony.git
$ cd symfony
$ git remote add upstream git://github.com/symfony/symfony.git
Antes de empezar, debes saber que todos los parches que envíes se deben liberar bajo la Licencia MIT, a menos que explícitamente lo especifiques en tus confirmaciones de cambios.
Antes de trabajar en tu parche, debes determinar en cual rama necesitas trabajar. La rama debe estar basada en la rama master si deseas agregar una nueva característica. Pero, si deseas corregir un fallo, utiliza la versión más antigua, pero aún mantenida de Symfony donde ocurre el fallo (como 2.0).
Nota
Todas las correcciones de fallos se fusionarán en las ramas de mantenimiento y además se fusionaran regularmente en las ramas más recientes. Por ejemplo, si envías un parche para la rama 2.0, el parche también será aplicado por el equipo del núcleo a la rama master.
Cada vez que desees trabajar en un parche para un fallo o una mejora, crea una rama para ese asunto:
$ git checkout -b NOMBRE_RAMA master
O, si deseas proporcionar una corrección de fallo para la rama 2.0, en primer lugar, actualiza tu copia local a la rama 2.0:
$ git checkout -t origin/2.0
Luego, crea una nueva rama de la rama 2.0 para trabajar en la corrección del fallo:
$ git checkout -b NOMBRE_RAMA 2.0
Truco
Utiliza un nombre descriptivo para tu rama (ticket_XXX donde XXX es el número del boleto, esta es una buena convención para la corrección de fallos).
La orden checkout anterior, automáticamente cambia el código a la rama recién creada (para ver la rama en que estás trabajando utiliza git branch).
Trabaja en el código tanto como quieras y confirma tus cambios tanto como desees; pero ten en cuenta lo siguiente:
Truco
Puedes comprobar los estándares de codificación de tu parche ejecutando el siguiente archivo que puedes conseguir aquí:
$ cd /ruta/a/symfony/src
$ php symfony-cs-fixer.phar fix . Symfony20Finder
Truco
Un buen mensaje de confirmación de cambios sustancial está compuesto por un resumen (en la primera línea), seguido opcionalmente por una línea en blanco y una descripción más detallada. El resumen debe comenzar con el componente en el que estás trabajando entre corchetes ([DependencyInjection], [FrameworkBundle], ...). Utiliza un verbo (fixed..., added..., ...) para iniciar el resumen y no agregues un punto al final.
Cuando tu parche no se trata de una corrección de fallo (cuando agregas una nueva característica o cambias una existente, por ejemplo), además debes incluir lo siguiente:
Siempre que sientas que tu parche esté listo para su presentación, sigue los siguientes pasos.
Antes de presentar tu revisión, actualiza tu rama (es necesario si te toma cierto tiempo terminar los cambios):
$ git checkout master
$ git fetch upstream
$ git merge upstream/master
$ git checkout NOMBRE_RAMA
$ git rebase master
Truco
Sustituye master con 2.0 si estás trabajando en una corrección de fallo
Al ejecutar la orden rebase, posiblemente tengas que arreglar conflictos de fusión. git status te mostrará los archivos sin fusionar. Resuelve todos los conflictos, y luego continua el rebase:
$ git add ... # Añade archivos resueltos
$ git rebase --continue
Comprueba que todas las pruebas todavía pasan y envía a tu rama remota:
$ git push origin NOMBRE_RAMA
Ahora puedes hacer una solicitud de atracción en el repositorio symfony/synfony de Github.
Truco
Ten cuidado de marcar tu solicitud de atracción para symfony:2.1 si deseas que el equipo del núcleo atraiga una corrección de fallo basada en la rama 2.1.
Para facilitar el trabajo del equipo del núcleo, siempre incluye los componentes modificados en el mensaje (en inglés) de tu solicitud de atracción, como este:
[Yaml] fixed something
[Form] [Validator] [FrameworkBundle] added something
La descripción de la solicitud de atracción debe incluir la siguiente lista de comprobación en la parte superior para garantizar que las aportaciones se pueden revisar sin la necesidad infinitos ciclos de retroalimentación y que tus aportaciones se pueden incluir a Symfony2 tan rápidamente como sea posible:
| Q | A
| ------------- | ---
| Bug fix? | [yes|no]
| New feature? | [yes|no]
| BC breaks? | [yes|no]
| Deprecations? | [yes|no]
| Tests pass? | [yes|no]
| Fixed tickets | [lista separada por comas de las entradas corregidas por el PR]
| License | MIT
| Doc PR | [Referencia a la documentación del PR, si la hay]
Un envío de ejemplo ahora se ve de la siguiente manera:
| Q | A
| ------------- | ---
| Bug fix? | no
| New feature? | no
| BC breaks? | no
| Deprecations? | no
| Tests pass? | yes
| Fixed tickets | #12, #43
| License | MIT
| Doc PR | symfony/symfony-docs#123
Debes incluir la tabla completa (no quites líneas que pienses que no son relevantes). Para errores tipográficos sencillos, cambios menores en la PHPDocs, o cambios en los archivos de traducción, usa la versión corta de la lista de comprobación:
| Q | A
| ------------- | ---
| Fixed tickets | [lista separada por comas de las entradas corregidas por el PR]
| License | MIT
Algunas respuestas a cuestiones que provocan algunos requisitos adicionales:
- Si contestaste yes a «Bug fix?», comprueba si el fallo ya está enumerado en los problemas de Symfony y proporciona una referencia a la(s) «entrada(s) corregida(s)»;
- Si contestaste yes a «New feature?», debes enviar una solicitud de atracción a la documentación y referirla bajo la sección «Doc PR»;
- Si contestaste yes a «BC breaks?», el parche debe contener actualizaciones a los archivos CHANGELOG y UPGRADE pertinentes;
- Si contestaste yes a «Deprecations?», el parche debe contener actualizaciones a los archivos CHANGELOG y UPGRADE pertinentes;
- Si contestaste no a «Tests pass», debes añadir un elemento a una lista de pendientes con las acciones que se deben tomar para corregir las pruebas;
- Si la «license» no es MIT, sólo no envíes la solicitud de atracción puesto que no será aceptada en ningún caso.
Si no cubres alguno de los requisitos anteriores, crea una lista de pendientes y añade los elementos pertinentes:
- [ ] fix the tests as they have not been updated yet
- [ ] submit changes to the documentation
- [ ] document the BC breaks
Si el código no está terminado todavía porque no tienes tiempo para acabarlo o porque quieres retroalimentación temprana sobre tu trabajo, añade un elemento a la lista de pendientes:
- [ ] finish the code
- [ ] gather feedback my changes
Mientras tengas elementos en la lista de pendientes, por favor prefija el título de la petición de atracción con «[WIP]».
En la descripción de tu solicitud de atracción, da tantos detalles como sea posible acerca de tus cambios (no dudes en dar ejemplos de código para ilustrar tus puntos). Si tu solicitud de atracción está a punto de añadir una nueva característica o modificar una existente, explica las razones para los cambios. La descripción de la solicitud de atracción ayuda a la revisión del código y sirve como referencia al fusionar el código (la descripción de la solicitud de atracción y todos tus comentarios asociados son parte del mensaje de confirmación de la fusión).
Además de este código de la solicitud de atracción, también debes enviar una solicitud de atracción al repositorio de documentación para actualizar la documentación cuando sea apropiado.
Basándote en la retroalimentación sobre tu solicitud de atracción, posiblemente debas volver a trabajar en tu parche. Antes de volver a presentarlo, reorganiza con upstream/master o upstream/2.0, no lo fusiones; y fuerza el envío al origen:
$ git rebase -f upstream/master
$ git push -f origin NOMBRE_RAMA
Nota
cuando haces un push --force, siempre especifica el nombre de la rama de forma explícita para evitar dañar otras ramas en el repositorio (--force le dice a Git que realmente quieres meterte con esas cosas por lo tanto hazlo con mucho cuidado).
A menudo, los moderadores te pedirán que «aplanes» tus confirmaciones de cambios. Lo cual significa que combines varias confirmaciones de cambios en una sola. Para ello, utiliza la orden rebase:
$ git rebase -i HEAD~3
$ git push -f origin NOMBRE_RAMA
Aquí, el número 3 debe ser igual a la cantidad de confirmaciones de cambios en tu rama. Después que escribas esta orden, aparecerá un editor mostrándote la lista de confirmaciones de cambios:
pick 1a31be6 first commit
pick 7fc64b4 second commit
pick 7d33018 third commit
Para revertir todas las confirmaciones de cambios a la primera, elimina la palabra «pick» antes de la segunda y última confirmación de cambios, y sustitúyela por la palabra «squash» o simplemente «s». Cuando guardes, Git iniciará el rebase, y si tiene éxito, te pedirá que edites el mensaje de confirmación, el cual de manera predefinida es una lista con todos los mensajes de las confirmaciones de cambios. Cuando hayas terminado, ejecuta la orden push.
