How to contribute to Symfony Version: 2.5

Transcription

1 How to contribute to Symfony Version:.5

2 How to contribute to Symfony (.5) This work is licensed under the Attribution-Share Alike 3.0 Unported license ( licenses/by-sa/3.0/). You are free to share (to copy, distribute and transmit the work), and to remix (to adapt the work) under the following conditions: Attribution: You must attribute the work in the manner specified by the author or licensor (but not in any way that suggests that they endorse you or your use of the work). Share Alike: If you alter, transform, or build upon this work, you may distribute the resulting work only under the same, similar or a compatible license. For any reuse or distribution, you must make clear to others the license terms of this work. The information in this book is distributed on an as is basis, without warranty. Although every precaution has been taken in the preparation of this work, neither the author(s) nor SensioLabs shall have any liability to any person or entity with respect to any loss or damage caused or alleged to be caused directly or indirectly by the information contained in this work. If you find typos or errors, feel free to report them by creating a ticket on the Symfony ticketing system ( Based on tickets and users feedback, this book is continuously updated.

3 Contents at a Glance Signaler un Bug...4 Soumettre un correctif...5 Signaler une faille de sécurité... Effectuer les tests Symfony... Standards syntaxiques...5 Conventions...8 License Symfony...0 Participer à la Documentation... Format de Documentation...5 Traductions...9 License destinée à la documentation de Symfony...3 Processus de sortie des versions...33 Réunions IRC...36 Autres Ressources...38 Contents at a Glance iii

4 Chapter Signaler un Bug Quand vous trouvez un bug dans Symfony, nous vous sommes reconnaissants de nous en avertir. Cela nous aide à rendre Symfony meilleur. Si vous pensez avoir trouvé une faille de sécurité, utilisez s'il vous plait cette procédure spécifique. Avant de soumettre un rapport de bug : Vérifiez par deux fois la documentation officielle afin de vous assurer que vous utilisez le framework correctement. Demander l'assistance d'utilisateurs de la liste de diffusion, du forum 3, ou du canal IRC 4 #symfony (ou #symfony-fr) si vous n'êtes pas complètement certain que le comportement observé soit un bug. Si votre problème ressemble finalement à un bug, signalez-le en utilisant le tracker 5 de bugs officiel en suivant ces règles simples : Utilisez le champ titre pour clairement décrire le problème; Décrivez les étapes nécessaires permettant de reproduire le bug en joignant si besoin de courts morceaux de code(fournir un test unitaire qui illustre le bug est une très bonne solution); Donnez autant de détails que possible sur votre environnement (OS, version PHP, version Symfony, extensions actives,...); (optionnel) Joignez un patch #contributing-code-irc:--irc.freenode.net-symfony 5. Chapter : Signaler un Bug 4

5 Chapter Soumettre un correctif Les patches représentent la meilleure manière de fournir une correction de bug ou de proposer des améliorations à Symfony. Step : Configurer votre environnement Installer les logiciels Avant de travailler sur Symfony, installez un environnement avec les logiciels suivants : Git; PHP version ou supérieur; PHPUnit ou supérieur. Configurer Git Spécifiez vos informations personnelles en définissant votre nom et une adresse fonctionnelle : Listing - $ git config --global user.name "Votre nom" $ git config --global user. votre_ @exemple.com Si vous découvrez Git, il vous est vivement recommandé de lire l'excellent livre gratuit ProGit. Si votre IDE crée les fichiers de configuration dans le répertoire de votre projet, vous pouvez utiliser le fichier global.gitignore (pour tout les projets) ou le fichier.git/info/exclude (par projet) pour les ignorer. Lisez la documentation Github.. Chapter : Soumettre un correctif 5

6 Pour les utilisateurs Windows : en installant Git, l'installeur vous demandera quoi faire avec les fins de lignes, et vous suggérera de remplacer tout les saut de lignes (LF pour Line Feed) par des fins de lignes (CRLF pour Carriage Return Line Feed). Ce n'est pas la bonne configuration si vous souhaitez contribuer à Symfony! Conserver la configuration par défaut est le meilleur choix à faire, puisque Git convertira vos sauts de ligne (Line Feed) conformément à ceux du dépôt. Si vous avez déjà installé Git, vous pouvez vérifier la valeur en tapant : Listing - $ git config core.autocrlf Cela retournera soit «false», «input» ou «true», «true» et «false» étant les mauvaises valeurs. Changez la en tapant : Listing -3 $ git config --global core.autocrlf input Remplacez --global par --local si vous ne voulez le changer que pour le dépôt actif. Récupérez le code source de Symfony Récupérez le code source de Symfony : Créez un compte GitHub 3 et authentifiez vous; Faites un Fork du dépôt Symfony 4 (cliquez sur le bouton «Fork»); Après que le «hardcore» est terminé, clonez votre fork localement (cela créera un dossier symfony) : Listing -4 $ git clone git@github.com:username/symfony.git Ajoutez le dépôt distant comme remote: Listing -5 $ cd symfony $ git remote add upstream git://github.com/symfony/symfony.git Vérifiez que les tests sont validés Maintenant que Symfony est installé, vérifiez que tout les tests unitaires passent sur votre environnement comme cela est expliqué dans le document dédié. Step : Travaillez sur votre patch La License Avant de commencer, vous devez savoir que tout les patchs que vous soumettrez devront être sous license MIT, à moins de le spécifier clairement dans vos commits Chapter : Soumettre un correctif 6

7 Choisissez la bonne branche Avant de travailler sur un patch, vous devez déterminer sur quelle branche vous devez travailler. La branche devrait être basée sur la branche master si vous souhaitez ajouter une nouvelle fonctionnalité. Mais si vous voulez corriger un bug, utiliser la dernière version maintenue de Symfony dans laquelle le bug apparaît (par exemple.0). Toute correction de bug mergée sur les branches de maintenance sera mergée sur une branche plus récente de manière régulière. Par exemple, si vous proposez une correction pour la branche.0, elle sera également appliquée sur la branche master par notre équipe. Créez une nouvelle branche Chaque fois que vous voulez travailler sur un patch lié à un bug ou à une nouvelle fonctionnalité, créez une nouvelle branche : Listing -6 $ git checkout -b NOM_BRANCHE master Ou, si vous voulez proposer un correctif pour un bug de la branche.0, récupérez la branche.0 distante localement : Listing -7 $ git checkout -t origin/.0 Puis créez une nouvelle branche basée sur la.0 pour travailler sur votre correctif : Listing -8 $ git checkout -b NOM_BRANCHE.0 Utilisez un nom explicite pour votre branche (ticket_xxx où XXX est le numéro du ticket est une bonne convention pour les corrections de bugs). La commande Checkout ci-dessus bascule automatiquement le code vers la branche nouvellement créée (vérifiez la branche sur laquelle vous vous trouvez avec git branch). Travaillez sur votre patch Travaillez sur le code autant que vous le désirez et commitez aussi souvent que vous le voulez mais gardez bien à l'esprit de : Respecter les standards (utilisez git diff --check pour vérifier les espaces en bout de ligne, lisez aussi le conseil ci-dessous); Ajouter des test unitaires afin de prouver que le bug est corrigé ou que la nouvelle fonctionnalité est opérationnelle; Tâcher de ne pas casser la rétrocompatibilité (si c'est le cas, essayez de fournir une couche de compatibilité pour supporter l'ancienne version). Les patchs non rétrocompatibles ont moins de chance d'être mergés; Faire des commits bien (utilisez le pouvoir du git rebase afin d'avoir un historique clair et logique); Supprimer les commits non pertinents qui concernent les standards de code ou les corrections de fautes de frappe dans votre propre code; Ne jamais corriger les standards de code dans le code existant car cela rend la revue de code plus difficile; Chapter : Soumettre un correctif 7

8 Écrire des messages parlants pour chacun des commits (lisez le conseil ci-dessous). Vous pouvez vérifier les standards de code de votre patch grâce à script 5 (source 6 ): Listing -9 $ cd /path/to/symfony/src $ php symfony-cs-fixer.phar fix. Symfony0Finder Un bon message de commit est composé d'un résumé succinct (la première ligne), suivi optionnellement par une ligne vide et par une description plus détaillée. Le résumé commence par le composant sur lequel vous êtes en train de travailler entre crochets ([DependencyInjection], [FrameworkBundle],...). Utilisez un verbe (fixed..., added...,...) pour commencer votre résumé et n'ajoutez pas de point à la fin. Préparez votre patch avant de le soumettre Si votre patch ne concerne pas une correction de bug (si vous ajoutez une nouvelle fonctionnalité ou si vous en modifiez une existante par exemple), il doit également inclure ce qui suit : Une explication des changements effectués dans le(s) fichier(s) CHANGELOG correspondant(s); Une explication sur comment mettre à jour une application existante dans le(s) fichier(s) UPGRADE correspondant(s), si vos changements ne sont pas rétrocompatibles. Step 3: Soumettez votre patch Lorsque vous pensez que votre patch est prêt à être envoyé, suivez les étapes suivantes. Mettez à jour votre patch avec rebase Avant de soumettre votre patch, mettez à jour votre branche (cela est nécessaire si vous avez mis du temp à terminer vos changements) : Listing $ git checkout master $ git fetch upstream $ git merge upstream/master $ git checkout NOM_BRANCHE $ git rebase master Remplacez master par.0 si vous travaillez sur une correction de bug. Lorsque vous utilisez la commande rebase, vous pourriez avoir des conflits lors du merge. git status affichera les fichiers non mergés. Résolvez tout les conflits avant de continuer le rebase : Listing Chapter : Soumettre un correctif 8

9 $ git add... # ajouter les fichiers traités $ git rebase --continue Vérifiez que tout les tests passent toujours et pushez votre branche sur le dépôt distant : Listing - $ git push origin NOM_BRANCHE Faites une Pull Request Vous pouvez maintenant faire une pull request sur le dépôt symfony/symfony. Assurez vous de faire pointer votre pull request vers symfony:.0 si vous voulez que notre équipe récupère une correction de bug basée sur la branche.0. Pour faciliter le travail de l'équipe, incluez toujours le nom du composant modifié dans votre message de pull request, comme ceci : Listing -3 [Yaml] fixed something [Form] [Validator] [FrameworkBundle] added something Veuillez utiliser le tag "[WIP]" dans le titre si la soumission n'est pas encore prête ou si les tests ne sont pas complet ou ne passent pas encore. La description de la Pull Request doit inclure la check list suivante afin de s'assurer que les contributions peuvent être relues et vérifiées sans échanges inutiles avec vous, et que vos contributions peuvent être inclues dans Symfony aussi vite que possible : Listing Bug fix: [yes no] Feature addition: [yes no] Backwards compatibility break: [yes no] Symfony tests pass: [yes no] Fixes the following tickets: [liste de tickets corrigés séparés par une virgule] Todo: [liste de choses restantes à faire] License of the code: MIT Documentation PR: [Référence de la documentation de la PR s'il y en a] Un exemple de soumission pourrait ressembler à ça : Listing Bug fix: no Feature addition: yes Backwards compatibility break: no Symfony tests pass: yes Fixes the following tickets: #, #43 Todo: - License of the code: MIT Documentation PR: symfony/symfony-docs#3 Dans la description de la Pull Request, donnez autant de détails que possible sur les changements (n'hésitez pas à donner des exemples de code pour illustrer vos propos). Si votre Pull Request concerne l'ajout ou la modification d'une fonctionnalité existante, expliquez les raisons de ce changement. La Chapter : Soumettre un correctif 9

10 description d'une Pull Request est utile lors de la revue de code est fait office de référence lorsque le code est mergé (la description de la Pull Request et tout les commentaires qui y sont associés font partie du message de commit du merge). En plus de cette Pull Request de «code», vous devez également envoyer une Pull Request au dépôt de la documentation 7 pour mettre à jour la documentation si besoin. Retravaillez votre patch Selon les retours que vous aurez sur votre Pull Request, vous pourriez avoir besoin de retravailler votre patch. Avant de le re-soumettre, faites un rebase avec upstream/master ou upstream/.0, ne mergez pas; et forcez le push vers origin : Listing -6 $ git rebase -f upstream/master $ git push -f origin NOM_BRANCHE lorsque vous faites un push --force, spécifiez toujours explicitement le nom de la branche pour éviter de mettre la pagaille dans votre dépôt (--force dit à git que vous voulez vraiment traiter des choses, donc faites attention). Souvent, les modérateurs vous demanderont «d'aplanir» vos commits. Cela signifie que vous devrez fusionner plusieurs commits en un seul. Pour faire cela, utilisez la commande rebase : Listing -7 $ git rebase -i HEAD~3 $ git push -f origin NOM_BRANCHE Ici, le nombre 3 doit être égal au nombre de commit de votre branche. Après que vous avez tapé cette commande, un éditeur vous affichera une liste de commits : Listing -8 3 pick a3be6 premier commit pick 7fc64b4 second commit pick 7d3308 troisième commit Pour fusionner tous les commits dans le premier, supprimez le mot «pick» avant le second et les derniers commits, et remplacez le par le mot «squash» ou juste «s». Quand vous enregistrez, git commencera le rebase et, quand il aura terminé, vous demandera de modifier le message de commit qui est, par défaut, une liste des messages de chaque commit. Lorsque vous aurez terminé, lancez la commande push. Pour que votre branche soit automatiquement testée, vous pouvez ajouter votre fork à travisci.org 8. Identifiez vous simplement en utilisant votre compte github.com et appuyez le bouton pour activer les tests automatiques. Dans votre Pull Request, plutôt que de spécifier «Symfony tests pass: [yes no]», vous pouvez faire un lien vers l'icône de statut travis-ci.org 9. Pour plus de détails, lisez le Guide de démarrage travis-ci.org 0. Cela peut être fait simplement en cliquant sur l'icone de la page de build de Travis. Sélectionnez votre branche puis copiez le contenu dans la description de la Pull Request Chapter : Soumettre un correctif 0

11 Chapter 3 Signaler une faille de sécurité Vous avez trouvé une faille de sécurité dans Symfony? N'utilisez pas la liste de diffusion ou le gestionnaire de bugs. Toutes les failles de sécurités doivent être transmises à security [at]symfonyproject.com. Les courriels envoyés à cette adresse sont retransmis à l'équipe centrale de Symfony à l'aide d'une liste de diffusion privée. Pour chaque rapport, nous essayons dans un premier temps de confirmer la vulnérabilité. Si elle est vérifiée, l'équipe centrale travaille sur une solution en suivant ces étapes :. Envoi d'un accusé de réception au rapporteur;. Travail sur un correctif; 3. Écriture d'un message décrivant la vulnérabilité, les utilisations possibles, et des moyens mis à disposition pour y pallier; 4. Application du correctif sur toutes les versions maintenues de Symfony; 5. Publication du message sur le blog officiel de Symfony. Tant que nous travaillons sur un correctif, s'il vous plait, ne révélez pas publiquement cette faille. Chapter 3: Signaler une faille de sécurité

12 Chapter 4 Effectuer les tests Symfony Avant de soumettre un patch pour inclusion, vous devrez lancer la suite de tests intégrée dans Symfony afin de vérifier que tout est fonctionnel. PHPUnit Pour lancer la suite de tests Symfony, commencez par installer PHPUnit 3.7 (ou plus). Dépendances (facultatif) Pour lancer la suite de tests complète, incluant les tests dépendants de bibliothèques externes, Symfony doit pouvoir auto-charger celles-ci. Par défaut, elles sont auto-chargées depuis le répertoire vendor/ dans le dossier racine (vérifier autoload.php.dist). La suite de tests a besoin des bibliothèques tierces suivantes : Doctrine Swiftmailer Twig Monolog Pour les installer, utilisez Composer : Étape : Récupérer Composer 3 Listing 4- curl -s php Assurez vous de télécharger composer.phar dans le même répertoire que celui où est situé le fichier composer.json. Étape : Installer les vendors Chapter 4: Effectuer les tests Symfony

13 Listing 4- $ php composer.phar --dev install Notez que le script peut prendre un certain temps avant de se terminer. Si vous n'avez pas curl d'installé, vous pouvez aussi simplement télécharger le fichier installer manuellement à 4. Déplacer ce fichier dans votre projet puis lancez les commandes : Listing 4-3 $ php installer $ php composer.phar --dev install Après installation, vous pouvez mettre à jour les vendors dans leur version la plus récente en lançant la commande suivante : Listing 4-4 $ php composer.phar --dev update Lancement Premièrement, mettez à jour les vendors (voir ci-dessus). Ensuite, lancez la suite de tests depuis la racine de Symfony à l'aide de la commande suivante : Listing 4-5 $ phpunit La sortie devrait afficher OK. Si ce n'est pas le cas, vous devez étudier les résultats afin de comprendre en quoi vos modifications ont altéré les résultats des tests. Si vous ne voulez tester qu'un seul composant, tapez son chemin après la commande phpunit, par exemple : Listing 4-6 $ phpunit src/symfony/component/finder/ Lancez la suite de tests avant d'appliquer vos modifications afin de vérifier qu'ils fonctionnent sur votre configuration. Couverture du code Si vous ajoutez de nouvelles fonctionnalités, vous devez également vérifier la couverture de code grâce à l'option coverage-html : 4. Chapter 4: Effectuer les tests Symfony 3

14 Listing 4-7 $ phpunit --coverage-html=cov/ Vérifiez la couverture de code en ouvrant la page générée cov/index.html dans un navigateur web. La couverture de code ne fonctionne que si vous avez activé XDebug et installé toutes les dépendances. Chapter 4: Effectuer les tests Symfony 4

15 Chapter 5 Standards syntaxiques Quand vous contribuez au code source de Symfony, vous devez suivre ses conventions de codage. Pour simplifier, la règle d'or est : Imiter le code existant de Symfony. De nombreux bundles open-source et bibliothèques utilisés au sein de Symfony suivent les mêmes lignes de conduites, vous devez donc les suivre vous aussi. Rappelez vous que l'avantage principal d'un standard est que toutes les parties du code source résultant se ressemblent et semblent ainsi familières, ce n'est pas que telle technique soit plus lisible qu'une autre. Symfony suit les standards définis par les documents PSR-0, PSR- et PSR- 3. Comme une image - ou un peu de code - est plus efficace qu'un long discours, voici un court exemple contenant les conventions les plus courantes décrites ci-dessous : Listing <?php /* * This file is part of the Symfony package. * * (c) Fabien Potencier <fabien@symfony.com> * * For the full copyright and license information, please view the LICENSE * file that was distributed with this source code. */ namespace Acme; class FooBar { const SOME_CONST = 4; private $foobar; /** Chapter 5: Standards syntaxiques 5

16 } string $dummy Some argument description */ public function construct($dummy) { $this->foobar = $this->transformtext($dummy); } /** string $dummy Some argument description array $options * string null Transformed input */ private function transformtext($dummy, array $options = array()) { $mergedoptions = array_merge($options, array( 'some_default' => 'values', )); } if (true === $dummy) { return; } if ('string' === $dummy) { if ('values' === $mergedoptions['some_default']) { $dummy = substr($dummy, 0, 5); } else { $dummy = ucwords($dummy); } } return $dummy; Structure Ajoutez un espace après chaque virgule séparatrice; Ajoutez un espace autour des opérateurs (==, &&,...); Ajoutez une ligne vide avant l'expression de retour return, à moins que le retour soit seul à l'intérieur du groupe parent (comme une expression if); Utilisez les accolades pour indiquer les structures de contrôle quel que soit le nombre d'expressions qu'elles entourent. Définissez une classe par fichier - cela ne s'applique pas à vos classes de helper privées qui ne sont pas appelées à être instanciée de l'extérieur. Elles ne sont pas concernées par le standard PSR-0; Déclarez les propriétés de vos classes avant les méthodes; Déclarez d'abord les méthodes publiques puis les protegées, et finalement les privées. Conventions de nommage Utilisez le camelcase, pas de underscore, pour les variables, les noms de méthodes et de fonctions, et les arguments; Utilisez les underscores pour les noms d'options et de paramètres; Chapter 5: Standards syntaxiques 6

17 Utilisez les espaces de nom pour toutes vos classes; Suffixez les interfaces avec Interface; Utilisez des caractères alphanumériques et des underscores pour les noms de fichier; Pensez à consulter la documentation Conventions pour obtenir des suggestions de nom. Documentation Ajoutez les blocs PHPDoc pour toutes les classes, méthodes, et fonctions; Omettez le si la méthode ne retourne rien; Les ne sont pas utilisées. Licence Symfony est réalisé sous licence MIT, un bloc licence doit être présent au début de chaque fichier PHP, avant l'espace de nom. Chapter 5: Standards syntaxiques 7

18 Chapter 6 Conventions Le document Standards syntaxiques décrit les conventions syntaxiques définies pour les projets Symfony et les bundles internes ou tiers. Ce document décrit les standards et conventions utilisés dans le coeur du framework afin de lui apporter consistence et prédictibilité. Vous êtes encouragés à les suivre dans votre propre code, mais n'êtes pas obligé. Nom des Méthodes Quand un objet a une relation many «principale» avec d'autres «choses» (objets, paramètres,...), les noms des méthodes sont normalisés : get() set() has() all() replace() remove() clear() isempty() add() register() count() keys() L'utilisation de ces méthodes est seulement autorisé quand il est certain que la relation décrite est la relation principale: un CookieJar possède de nombreux objets Cookie; un service Container a de nombreux services et de nombreux paramètres (comme le service est sa relation principale, la convention de nommage est utilisé pour cette relation); Chapter 6: Conventions 8

19 une commande de Console a de nombreux arguments et de nombreuses options. Il n'existe pas de relation principale, la convention de nommage ne s'applique donc pas. Pour les relations où la convention de nommage ne s'applique pas, les méthodes suivantes doivent être utilisées (XXX est le nom de la chose en relation): Relation principale get() set() n/a has() all() replace() remove() clear() isempty() add() register() count() keys() Autre Relations getxxx() setxxx() replacexxx() hasxxx() getxxxs() setxxxs() removexxx() clearxxx() isemptyxxx() addxxx() registerxxx() countxxx() n/a Notez que si «setxxx» et «replacexxx» sont très similaires, il y a tout de même une différence notable : «setxxx» peut remplacer, ou ajouter de nouveaux éléments à une relation. Avec «replacexxx», il est interdit d'ajouter des éléments, et une exception est lancée si l'élément identifié n'existe pas. Chapter 6: Conventions 9

20 Chapter 7 License Symfony Symfony est réalisé sous licence MIT. D'après Wikipedia : "C'est une licence de logiciel libre et open source, non copyleft, permettant donc d'inclure des modifications sous d'autres licences, y compris non libres. La licence donne à toute personne recevant le logiciel le droit illimité de l'utiliser, le copier, le modifier, le fusionner, le publier, le distribuer, le vendre et de changer sa licence. La seule obligation est de mettre le nom des auteurs avec la notice de copyright." La License Copyright (c) Fabien Potencier Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.. Chapter 7: License Symfony 0

21 Chapter 8 Participer à la Documentation La documentation est aussi importante que le code. Elle suit exactement les mêmes principes : DRY, testée, facile à maintenir, extensible, optimisée, et factorisée dans un soucis de concision. Contribuer Avant de contribuer, vous devez maîtriser le language markup rest utilisé dans la documentation. La documentation Symfony est hébergée sur GitHub: Listing 8- Si vous voulez soumettre un correctif, forkez le dépôt officiel sur GitHub et clonez votre dépot : Listing 8- $ git clone git://github.com/yourusername/symfony-docs.git Conformément au code source de Symfony, le dépôt de la documentation est séparé en de multiples branches correspondant aux différentes versions de Symfony. La branche master est la branche de développement des versions à venir. A moins que vous ne documentiez une fonctionnalité nouvelle, vos changements doivent toujours être basés sur la branche.3 plutôt que sur la branche master. Pour effectuer ceci faites un checkout la branche.3 : Listing 8-3 $ git checkout.3 Ensuite, créez une branche dédiée pour vos changements : Listing 8-4 $ git checkout -b improving_foo_and_bar. Chapter 8: Participer à la Documentation

22 Vous pouvez maintenant appliquer vos changements directement à cette branche et les commiter. Ensuite, envoyez cette branche à votre dépôt et initiez une requête (pull request). Celle-ci devra être entre votre branche improving_foo_and_bar et la branche symfony-docs master. Si vous avez basé vos changement sur la branche.3 vous devez changer la branche de base pour qu'elle soit.3 sur la page de prévisualisation : Tout les changements faits sur la branche.3 seront mergés chaque semaine dans la branche.4 qui sera ensuite mergée sur la branche master pour la prochaine version. GitHub explique en détail les requêtes de mise à jour ou pull requests. La documentation Symfony est sous licence Creative Commons Attribution-Share Alike 3.0 Unported Licence. Soyez patient, vos changements peuvent mettre de 5 minutes à plusieurs jours après que l'équipe de documentation a mergé votre pull request avant d'être visibles sur le site symfony.com. Vous pouvez vérifier si vos changements ont introduit des erreurs de syntaxe en allant sur la page Erreurs de génération de la documentation 3 (elle est mise à jour chaque nuit à 3h du matin quand le serveur génère la documentation). Standards Dans le but d'aider le lecteur autant que possible, et de créer des exemples de code qui semblent familiers, vous devriez suivre ces règles : Le code suit les Standards de code Symfony ainsi que les Standards de code Twig 4 ; Chaque ligne devrait se terminer après le premier mot qui dépasse le 7ème caractère (ainsi, la plupart des lignes font environ 7 à 78 caractères); Lorsque vous n'affichez pas une ou plusieurs lignes de code, vous placez... en commentaire à l'endroit où les lignes sont censées se trouver. Ces commentaires sont : //... (php), #... (yaml/bash), {#... #} (twig), <! > (xml/html), ;... (ini),... (text); Lorsque vous cachez une partie d'une ligne, par exemple une variable, placez... (sans commentaire) à l'endroit où elle est censée être; Chapter 8: Participer à la Documentation

23 Description du code caché : (facultatif) Si vous cachez plusieurs lignes : la description peut être placée après les... Si vous ne cachez qu'une partie de la ligne : la description peut être placée avant la ligne; Si c'est utile, un bloc de code devrait commencer par un commentaire indiquant le nom du fichier qui contient le code. Ne mettez pas de ligne vide après ce commentaire, à moins que la prochaine ligne ne soit également un commentaire; Vous devriez mettre un $ devant chaque ligne de commande; Le raccourci :: est préféré à.. code-block:: php pour commencer un block de PHP. Un exemple: Listing // src/foo/bar.php //... class Bar { //... } public function foo($bar) { // définit foo avec la valeur de bar $foo =...; } //... vérifie si $bar a la bonne valeur return $foo->baz($bar,...); En Yaml vous devriez mettre un espace après { et avant } (ex { _controller:... }), mais pas en Twig (ex {'hello' : 'value'}). Un élément de tableau est une partie de ligne, pas une ligne complète. Vous ne devriez donc pas utiliser //... mais..., (la virgule est là pour les standards de code): Listing array( 'une valeur',..., ) Signaler une erreur La contribution la plus facile que vous pouvez effectuer est de signaler une erreur : une faute de frappe, une grammaire imparfaite, un exemple de code erroné, une explication manquante... Étapes: Soumettez un bogue dans le gestionnaire de bogues; (optionnel) Proposez un correctif. Chapter 8: Participer à la Documentation 3

24 Traductions Lisez la documentation dédiée traductions. Chapter 8: Participer à la Documentation 4

25 Chapter 9 Format de Documentation La documentation Symfony utilise restructuredtext comme format d'écriture et Sphinx pour produire les documents dans d'autres formats (HTML, PDF,...). restructuredtext restructuredtext «est une syntaxe ce-que-vous-voyez-est-ce-que-vous-obtenez (wysiwyg) facile à lire et un analyseur (parser)». Vous pouvez apprendre la syntaxe rst en lisant la documentation 3 Symfony existante ou en lisant les bases de restructuredtext 4 sur le site de Sphinx. Si vous êtes familier avec Markdown, soyez attentif à certains concepts qui semblent très similaires mais sont différents : Les listes commencent au début de la ligne (aucune indentation n'est permise); Les lignes de codes utilisent des double ticks (``comme ceci``). Sphinx Sphinx est un système de génération qui ajoute certaines fonctionnalités sympas permettant de créer une documentation à partir de documents restructuredtext. Il ajoute de nouvelles directives et des fonctions comme le standard rest markup 5. Coloration syntaxique Tout exemple de code utilise PHP comme schéma de coloration syntaxique par défaut. Vous pouvez changer cela à l'aide de la directive code-block : Chapter 9: Format de Documentation 5

26 Listing code-block:: yaml { foo: bar, bar: { foo: bar, bar: baz } } Si votre code PHP débute par <?php, vous devrez utiliser html+php comme pseudo-language de coloration : Listing code-block:: html+php <?php echo $this->foobar();?> Une liste des langages supportés ainsi que leurs noms respectifs est disponible sur le site web Pygments 6. Blocs de configurations Si vous affichez une configuration, vous devez utiliser la directive configuration-block dans tous les formats de configuration supportés (PHP, YAML, et XML) Listing configuration-block::.. code-block:: yaml # Configuration in YAML.. code-block:: xml <!-- Configuration in XML //-->.. code-block:: php // Configuration in PHP Le code rest précédent sera affiché comme cela : Listing 9-4 # Configuration in YAML La liste des formats supportés : Identifiant du Format html xml php yaml jinja html+jinja Affichage HTML XML PHP YAML Twig Twig 6. Chapter 9: Format de Documentation 6

27 Identifiant du Format jinja+html php+html html+php ini php-annotations Affichage Twig PHP PHP INI Annotations Ajouter des liens Pour ajouter des liens à d'autres pages dans les documents, utilisez la syntaxe suivante : Listing 9-5 :doc:`/path/to/page` En utilisant le chemin et le nom du fichier de la page sans l'extension, par exemple : Listing :doc:`/book/controller` :doc:`/components/event_dispatcher/introduction` :doc:`/cookbook/configuration/environments` Le texte du lien sera le titre principal du document vers lequel pointe le lien. Vous pouvez aussi spécifier un autre texte pour le lien : Listing 9-7 :doc:`spooling </cookbook/ /spool>` Vous pouvez aussi ajouter des liens vers la documentation de l'api : Listing :namespace:`symfony\\component\\browserkit` :class:`symfony\\component\\routing\\matcher\\apacheurlmatcher` :method:`symfony\\component\\httpkernel\\bundle\\bundle::build` et vers la documentation de PHP : Listing :phpclass:`simplexmlelement` :phpmethod:`datetime::createfromformat` :phpfunction:`iterator_to_array` Tester une Documentation Afin de tester une documentation avant de la proposer : Installez Sphinx 7 ; Exécutez l'installeur Installation rapide de Sphinx 8 ; Installez les extensions Sphinx (voir plus bas); Chapter 9: Format de Documentation 7

28 Executez make html et relisez le code HTML généré dans le répertoire build. Installer les extensions Sphinx Télécharger l'extension depuis le dépôt source 9 Copiez le répertoire sensio vers le dossier _exts dans le répertoire racine (où se trouve conf.py) Ajouter les instructions suivantes au fichier conf.py : Listing #... sys.path.append(os.path.abspath('_exts')) # ajouter PhpLexer from sphinx.highlighting import lexers from pygments.lexers.web import PhpLexer #... # ajoute les extensions à la liste des extensions extensions = [..., 'sensio.sphinx.refinclude', 'sensio.sphinx.configurationblock', 'sensio.sphinx.phpcode'] # active la coloration syntaxique par défaut pour le code PHP qui n'est pas entre ``<?php...?>`` lexers['php'] = PhpLexer(startinline=True) lexers['php-annotations'] = PhpLexer(startinline=True) # ajoute PHP comme domaine principal primary_domain = 'php' # Ajoute les urls pour les liens vers l'api api_url = ' Chapter 9: Format de Documentation 8

29 Chapter 0 Traductions La documentation Symfony est écrite en anglais et de nombreuses personnes participent au processus de traduction. Participer D'abord devenez familier avec le markup language utilisé par la documentation. Ensuite, souscrivez à la liste de diffusion Symfony docs mailing-list, tout se déroule là. Finalement, trouvez le dépot principal du langage auquel vous voulez contribuer. Voici une liste des dépots officiel: Anglais: Français: 3 Italien: 4 Japonais: 5 Polonais: 6 Portugais (Brésilien): 7 Roumain: 8 Russe: 9 Espagnol: 0 Turc: Chapter 0: Traductions 9

30 Si vous voulez participer à la traduction d'un nouveau langage, lisez la section dédiée. Rejoindre l'équipe de traduction Si vous voulez aider à traduire certains documents dans votre langue ou corriger des erreurs, rejoigneznous; c'est un processus simple : Présentez vous sur la liste de diffusion Symfony docs mailing-list ; (optionnel) Proposer les sujets sur lesquels vous pouvez travailler ; Forker le dépôt master de votre language (clic sur le bouton "Fork" sur la page github) ; Traduisez certains documents et envoyé les sur votre dépôt ; Effectuer une requête de mise à jour (clic sur le bouton "Pull Request" de votre page sur GitHub) ; Le chef d'équipe accepte vos modifications et les fusionnent avec le dépôt master ; Le site de la documentation est mis à jour toutes les nuits à partir du dépôt du chef d'équipe. Ajouter une nouvelle langue Cette section présente le guide à suivre pour commencer la traduction de la documentation de Symfony dans une nouvelle langue. Commencer une traduction représente une masse de travail importante, parlez en sur la liste de diffusion Symfony docs mailing-list 3 et essayez de trouver des gens motivés pour vous aider. Quand l'équipe est prête nommé un chef d'équipe, ; il aura la responsabilité du dépôt principal (master). Créer le dépôt et copier les documents en anglais. L'équipe peut maintenant commencer son travail de traduction. Quand l'équipe est certaine que le dépôt est stable et à jour (tout est traduit, ou les documents non traduits ont été supprimés des sommaires (toctree -- correspondants aux fichiers dénommés index.rst et map.rst.inc), le chef d'équipe peut demander que le dépôt soit ajouté à la liste officielle des dépôt master en envoyant un courriel à Fabien (fabien at symfony.com). Maintenance Le processus de traduction ne s'arrête pas quand tout est traduit. La documentation est régulièrement mise à jour, déplacée (des nouveaux documents sont ajoutés, des bogues sont fixés, des paragraphes sont réorganisés,...). L'équipe de traduction a besoin de suivre le dépot anglais et d'appliquer les changement aux documents traduits aussitôt que possible. Les langues non maintenues sont supprimées de la liste officielle des dépôts car mettre à disposition une documentation obsolète comporte des risques dangereux Chapter 0: Traductions 30

31 Chapter License destinée à la documentation de Symfony La documentation Symfony est soumise à la licence Creative Commons Attribution-Share Alike 3.0 Unported License. En voici le résumé officiel en français : Paternité - Partage à l'identique CC BY-SA Cette licence permet aux autres de remixer, arranger, et adapter votre oeuvre, même à des fins commerciales, tant qu'on vous accorde le mérite en citant votre nom et qu'on diffuse les nouvelles créations selon des conditions identiques. Cette licence est souvent comparé aux licences de logiciels libres open source ou copyleft. Toutes les nouvelles oeuvres basées sur les vôtres auront la même licence, et toute oeuvre dérivée pourra être utilisée même à des fins commerciales. C'est la licence utilisée par Wikipédia ; elle est recommandée pour des oeuvres qui pourraient bénéficier de l'incorporation de contenu depuis Wikipédia et d'autres projets sous licence similaire. You are free: to Share to copy, distribute and transmit the work; to Remix to adapt the work. Under the following conditions: Attribution You must attribute the work in the manner specified by the author or licensor (but not in any way that suggests that they endorse you or your use of the work); Share Alike If you alter, transform, or build upon this work, you may distribute the resulting work only under the same or similar license to this one. With the understanding that: Waiver Any of the above conditions can be waived if you get permission from the copyright holder;. Chapter : License destinée à la documentation de Symfony 3

32 Public Domain Where the work or any of its elements is in the public domain under applicable law, that status is in no way affected by the license; Other Rights In no way are any of the following rights affected by the license: Your fair dealing or fair use rights, or other applicable copyright exceptions and limitations; The author's moral rights; Rights other persons may have either in the work itself or in how the work is used, such as publicity or privacy rights. Notice For any reuse or distribution, you must make clear to others the license terms of this work. The best way to do this is with a link to this web page. This is a human-readable summary of the Legal Code (the full license) Chapter : License destinée à la documentation de Symfony 3

33 Chapter Processus de sortie des versions Ce document explique le processus de sortie des versions de Symfony (Symfony étant le code hébergé sur le dépôt Git symfony/symfony). Symfony gère ses versions via un modèle basé sur la date; une nouvelle version de Symfony sortira tout les six mois, une en mai et une en novembre. Ce processus a été adopté à partir de Symfony., et toutes les «règles» expliquées dans ce document devront être scrupuleusement respectées à partir de Symfony.4. Développement La période de six mois est divisées en deux phases : Développement : Quatre mois pour ajouter de nouvelles fonctionnalités et améliorer celles existantes; Stabilisation: Deux mois pour corriger les bugs, préparer la version et attendre que tout l'écosystème Symfony (bibliothèques tierces, bundles et projets qui utilisent Symfony) se mettent à jour. Durant la phase de développement, toute nouvelle fonctionnalité peut être mise de côté si elle n'est pas finalisée à temps, ou si elle n'est pas suffisamment stable pour être intégrée à la version finale. Maintenance Chaque version de Symfony est maintenue pendant une période fixe, ce qui dépend du type de version.. Chapter : Processus de sortie des versions 33

34 Version standard Une version standard est maintenue pendant une période huit mois. Version «Long Term Support» Tout les deux ans, une version Long Term Support (version LTS) est publiée. Chaque version LTS est supportée pendant une période de trois ans. Après la période de support de trois ans fourni par la communauté, un support payant est disponible auprès de SensioLabs. Planning Voici le planning des quelques premières version qui utilisent ce modèle : Jaune représente la phase de développement Bleu représente la phase de stabilisation Vert représente la phase de maintenance Cela permet de connaitre précisément les dates de sortie et les périodes de maintenance. (special) Symfony. sortira fin février 03; (special) Symfony.3 (première LTS) sortira fin mai 03; Symfony.4 sortira fin november 03; Symfony.5 sortira fin mai 04; Chapter : Processus de sortie des versions 34

35 Rétrocompatibilité Après la sortie de Symfony.3, la rétro compatibilité sera conservée à tout prix. Si ce n'est pas possible, la fonctionnalité, l'amélioration ou la correction de bug sera programmée pour la prochaine version majeure : Symfony 3.0. Le travail sur Symfony 3.0 commencera dès qu'il y aura suffisamment de fonctionnalités majeures non rétrocompatibles en attente sur la todo liste. Explications Ce processus a été adopté pour fournir plus de visibilité et de transparence. Il a été établi selon les objectifs suivants : Raccourcir le cycle de sortie (permettre aux développeurs de bénéficier des nouvelles fonctionnalités plus rapidement); Donner plus de visibilité aux développeurs qui utilisent le framework ou les projets opensource qui utilisent Symfony; Améliorer l'expérience des contributeurs du coeur de Symfony: chacun sait quand une fonctionnalité sera disponible dans Symfony; Coordonner l'évolution de Symfony avec les projets PHP qui fonctionnent bien avec Symfony et les projets qui utilisent Symfony; Donner du temps à l'écosystème Symfony pour se mettre à jour avec les nouvelles versions (auteurs de bundles, contributeurs de documentation, traducteurs,...). La période de six mois a été choisie pour que deux versions puissent sortir par an. Cela permet également d'avoir pas mal de temps pour travailler sur de nouvelles fonctionnalités, et cela permet également aux fonctionnalités qui ne sont pas prêtes à temps de ne pas attendre trop longtemps avant d'être intégrées dans la sortie du prochain cycle. Le mode de maintenance dual a été choisi pour correspondre à chaque utilisateur de Symfony. Ceux qui bougent vite et veulent travailler avec la meilleure et la dernière version utiliseront les versions standard : une nouvelle version est publiée tout les six mois et il y a une période de mise à jour de deux mois. Les entreprises qui veulent plus de stabilité utiliseront les versions LTS : une nouvelle version est publiée tout les deux ans et il y a une période de mise à jour d'un an. Chapter : Processus de sortie des versions 35

36 Chapter 3 Réunions IRC L'objectif de ces réunions est de discuter de sujets en temps réel avec de nombreux développeurs Symfony. Tout le monde peut proposer un sujet sur la liste de diffusion symfony-dev jusqu'à 4h avant le début de la réunion, idéalement en incluant des informations préparées et pertinentes via des URLs. 4 heures avant la réunion un lien vers un doodle contenant la liste des sujets proposés sera publié. Tout le monde peut voter sur les sujets jusqu'au début de la réunion afin de définir l'ordre de l'agenda. Chaque sujet sera limité à 5 minutes et la réunion à une heure, laissant ainsi le temps nécessaire pour aborder 4 sujets. Noter que le but attendu d'une réunion n'est pas de trouver des solutions finalisées, mais bien plus de s'assurer qu'il existe une compréhension commune d'un problème particulier et ainsi de faire progresser la discussion à l'aide d'un outil de communication en temps réel apportant intrinsèquement des avantages aux échanges de points de vue. Ces réunions sont conduites chaque jeudi à 7:00 CET (+0:00) sur le channel #symfony-dev sur le serveur IRC Freenode. Les logs 3 IRC sont ensuite publiés sur le wiki, en incluant un court résumé pour chacun des sujets abordés. Des tickets sont créés pour chacune des tâches ou chacun des problèmes identifiés pendant la réunion et sont référencés dans le résumé. Quelques lignes directrices et informations concernant la participation : il est possible de changer vos votes jusqu'au début de la réunion en cliquant sur "Edit an entry"; Le doodle sera fermé aux votes au début de la réunion; L'agenda est défini par les sujets ayant le plus de votes dans le doodle, ou dans le cas d'une égalité par l'ordre des propositions (premier proposé, premier traité); Au début de la réunion une personne s'identifiera comme modérateur; Le modérateur est essentiellement responsable de s'assurer de la limite de temps de 5min et de s'assurer que les tâches sont clairement identifiées; Habituellement le moderateur écrira aussi le résumé et créera les tickets à moins que quelqu'un d'autre ne se propose; Chapter 3: Réunions IRC 36

37 Toute personne peut joindre la réunion et est explicitement invitée à participer; Idéalement chacun doit se familiariser avec les sujets abordés avant la réunion; Quand un nouveau sujet est abordé l'auteur est invité à présenter le sujet en quelques mots; Chacun peut ensuite commenter le sujet suivant sa propre vision; Suivant le nombre de personnes participantes vous devez vous retenir d'exposer des arguments trop spécifiques et/ou ardus; Rappelez vous que les logs 4 IRC seront publiés, et que de nombreuses personnes pourront relire vos commentaires; Les personnes sont encouragées à être volontaires pour prendre en charge les tâches définies durant la réunion. Voici un exemple 5 de doodle Chapter 3: Réunions IRC 37