La documentación es tan importante como el código. Esta sigue exactamente los mismos principios: una vez y sólo una, pruebas, facilidad de mantenimiento, extensibilidad, optimización y reconstrucción sólo por nombrar algunos. Y, por supuesto, la documentación tiene errores, errores tipográficos, guías difíciles de leer y mucho más.
Antes de colaborar, necesitas familiarizarte con el lenguaje de marcado empleado en la documentación.
La documentación de Symfony2 se encuentra alojada en GitHub:
https://github.com/symfony/symfony-docs
Si deseas enviar un parche bifurca el repositorio oficial en GitHub y luego clona tu bifurcación:
$ git clone git://github.com/TUNOMBRE/symfony-docs.git
Consistent with Symfony’s source code, the documentation repository is split into multiple branches: 2.0, 2.1, 2.2 corresponding to the different versions of Symfony itself. The master branch holds the documentation for the development branch of the code.
Unless you’re documenting a feature that was introduced after Symfony 2.0 (e.g. in Symfony 2.1), your changes should always be based on the 2.0 branch. To do this checkout the 2.0 branch before the next step:
$ git checkout 2.0
Truco
Your base branch (e.g. 2.0) will become the “Applies to” in the Formato de la solicitud de atracción that you’ll use later.
A continuación, crea una rama dedicada a tus cambios (para mantenerla organizada):
$ git checkout -b improving_foo_and_bar
Ahora puedes hacer los cambios directamente en esta rama y confirmarlos ahí. Cuando hayas terminado, impulsa esta rama a tu GitHub e inicia una solicitud de atracción.
Siguiendo el ejemplo, la solicitud de atracción de manera predeterminada debe ser entre tu rama improving_foo_and_bar y la rama master de symfony-docs.
Si has hecho tus cambios basándote en la rama 2.0, entonces necesitas cambiar la rama base para que sea 2.0 en la página anterior:
Nota
Todos los cambios hechos a una rama (p. ej. 2.0) serán fusionados en cada «nueva» rama (p. ej. 2.1, maestra, etc.) para la siguiente liberación en una base semanal.
GitHub aborda en detalle el tema de las solicitudes de atracción.
Nota
La documentación de Symfony2 está bajo una licencia Creative Commons Attribution-Share Alike 3.0 Unported Licencia.
You can also prefix the title of your pull request in a few cases:
Unless you’re fixing some minor typos, the pull request description must include the following checklist to ensure that contributions may be reviewed without needless feedback loops and that your contributions can be included into the documentation as quickly as possible:
| Q | A
| ------------- | ---
| Doc fix? | [yes|no]
| New docs? | [yes|no] (PR # si es aplicable en symfony/symfony)
| Applies to | [numero de versiones Symfony a las que es aplicable]
| Fixed tickets | [lista separada por comas de los boletos corregidos por PR]
Un envío de ejemplo ahora se ve de la siguiente manera:
| Q | A
| ------------- | ---
| Doc fix? | yes
| New docs? | yes (symfony/symfony#2500)
| Applies to | all (or 2.1+)
| Fixed tickets | #1075
Truco
Por favor, ten paciencia. Puede tomar desde 15 minutos hasta varios días para que tus cambios aparezcan en el sitio web symfony.com después de que el equipo de documentación fusione tu solicitud de atracción. Puedes comprobar si tus cambios introducen algunas cuestiones sobre el marcado yendo a la página de Errores en la generación de documentación (esta se actualiza en Francia cada noche a las 3 a.m. cuando el servidor vuelve a generar la documentación).
Si estás documentando un nuevo tipo de característica o un cambio que se esté haciendo en Symfony2, deberías preceder tu descripción del cambio con una etiqueta .. versionadded:: 2.X y una breve descripción:
.. versionadded:: 2.2
El método ``askHiddenResponse`` se añadió en *Symfony 2.2*.
Además, puedes hacer una pregunta y ocultar la respuesta. Esto particularmente es...
Si estás documentando un cambio de comportamiento, puedría ser útil describir brevemente cómo ha cambiado tal comportamiento.
.. versionadded:: 2.2
La función ``include()`` es una nueva característica de *Twig* que está disponible en *Symfony 2.2*. Anteriormente se utilizaba la etiqueta ``{% include %}``.
Siempre que se libere una nueva versión menor de Symfony2 (p. ej. 2.3, 2.4, etc.), se crea una nueva rama de la documentación desde la rama maestra. En este punto, todas las etiquetas versionadded para las versiones de Symfony2 que han alcanzado su fin-de-vida serán eliminadas. Por ejemplo, si Symfony 2.5 fuera liberado hoy, y 2.2 recientemente alcanzó su fin-de-vida, la etiqueta versionadded 2.2 sería eliminada de la nueva rama 2.5.
Con el fin de ayudar lo más posible al lector y crear código de ejemplo que se vea y sienta familiar, debes seguir estas reglas:
Un ejemplo:
// src/Foo/Bar.php
// ...
class Bar
{
// ...
public function foo($bar)
{
// ajusta foo al valor de bar
$foo = ...;
// ... comprueba si $bar tiene el valor correcto
return $foo->baz($bar, ...);
}
}
Prudencia
en Yaml debes dejar un espacio después de { y antes de } (p. ej. { _controlador: ... }), pero esto no lo debes hacer en Twig (p. ej. {'hola' : 'valor'}).
La contribución más sencilla que puedes hacer es reportar algún problema: a typo, a grammar mistake, a bug in a code example, a missing explanation, and so on.
Pasos a seguir:
Lee el documento dedicado.
