How to contribute to Symfony for Symfony 2.0

Transcript

1 How to contribute to Symfony for Symfony.0

2 How to contribute to Symfony (.0) 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 Segnalare un bug...4 Inviare una patch...5 Segnalazione di un problema di sicurezza...11 Eseguire i test di Symfony...1 Standard del codice...14 Convenzioni...17 Licenza di Symfony...19 Contribuire alla documentazione...0 Formato della documentazione... Traduzioni...5 Licenza della documentazione di Symfony...7 Incontri su IRC...9 Altre risorse...31 Contents at a Glance iii

4 Chapter 1 Segnalare un bug Se si dovesse trovare un bug in Symfony, chiediamo di segnalarlo. Ciò aiuta a rendere migliore Symfony. Se si ritiene di aver trovato un problema di sicurezza, si prega di seguire invece la procedura. Prima di inviare un bug: Ricontrollare la documentazione 1 ufficiale per verificare che non si stia facendo un uso scorretto del framework; Chiedere assistenza alla lista degli utenti, al forum 3 o al canale IRC 4 #symfony, se non si è sicuri che sia effettivamente un bug. Se si hanno problemi a identificare effettivamente il bug, segnalarlo utilizzando il tracker 5 ufficiale, seguendo alcune regole di base: Utilizzare il campo titolo per descrivere chiaramente il problema; Descrivere i passi necessari per riprodurre il bug, anche con brevi esempi di codice (fornire un test unitario per replicare il bug è il modo migliore) Fornire il maggior numero di dettagli possibile sul proprio ambiente (sistema operativo, versione di PHP versione di Symfony, extensioni abilitate,...) (facoltativo) Allegare una patch #contributing-code-irc:--irc.freenode.net-symfony 5. Chapter 1: Segnalare un bug 4

5 Chapter Inviare una patch Una patch è il modo migliore per rimediare a un bug e per proporre dei miglioramenti a Symfony Passo 1: preparare l'ambiente Installare il software Prima di lavorare con Symfony, preparare l'ambiente con il seguente software: Git; PHP versione 5.3. o successive; PHPUnit o successivi. Configurare Git Impostare le informazioni utente con il proprio nome reale e il proprio indirizzo di posta elettronica: Listing -1 1 $ git config --global user.name "Il proprio nome" $ git config --global user. la_propria_ @example.com Si raccomanda caldamente a chi fosse nuovo la lettura del libro ProGit 1, eccellente e libero. Se il proprio IDE crea dei file di configurazione dentro la cartella del progetto, si può usare il file globale.gitignore (per tutti i progetti) o il file.git/info/exclude (per progetto) per ignorarli. Vedere la documentazione di Github Chapter : Inviare una patch 5

6 Utenti di Windows: quando si installa Git, l'installazione chiederà cosa fare con i fine riga, suggerendo di sostituire Lf con CRLF. Questa impostazine è sbagliata, se si vuole contribuire a Symfony! Impostare il metodo "as-is" come scelta migliore, così git convertirà i fine riga con quelli nel repository. Se git è già stato installato, si può verificare questa impostazione con: Listing - 1 $ git config core.autocrlf Restituirà "false", "input" o "true", dove "true" e "false" sono i valori sbagliati. Impostare nuovamente con: Listing -3 1 $ git config --global core.autocrlf input Sostituire --global con --local se si vuole impostare solo per il repository attivo. Ottenere il codice sorgente di Symfony Ottenere il codice sorgente di Symfony: Creare un account su GitHub 3 ed entrare; Forkare il repository di Symfony 4 (cliccando sul bottone "Fork"); Dopo che l'azione "hardcore forking" è stata completata, clonare il proprio fork in locale (creerà una cartella symfony): Listing -4 1 $ git clone git@github.com:username/symfony.git Aggiungere il repository upstream come remote: Listing -5 1 $ cd symfony $ git remote add upstream git://github.com/symfony/symfony.git Verificare che i test passino Ora che Symfony è installato, verifcare che tutti i test unitari passino nel proprio ambiente, come spiegato nel documento dedicato. Passo : lavorare su una patch La licenza Prima di iniziare, occorre sapere che tutte le patch da inviare devono essere rilasciate sotto licenza MIT, a meno che non sia specificato diversamente nel proprio codice Chapter : Inviare una patch 6

7 Scegliere il ramo giusto Prima di lavorare su una patch, è necessario individuare il ramo giusto. Il ramo deve essere basato sul ramo master se si vuole aggiungere una nuova funzionalità. Ma se si vuole risolvere un bug, utilizzare le versioni vecchie (ma ancora mantenute) di Symfony nelle quali appare il bug (come.0). Tutti i bug risolti in rami di manutenzione sono inseriti anche i rami più recenti, su base regolare. Per esempio, se si invia una patch per il ramo.0, la patch sarà applicata anche sul ramo master. Creare un ramo Ogni volta che si vuole lavorare su una patch per un bug o un miglioramento, creare un ramo: Listing -6 1 $ git checkout -b NOME_RAMO master Oppure, se si vuole risolvere un bug per il ramo.0, tracciare il ramo.0 remoto in locale: Listing -7 1 $ git checkout -t origin/.0 Quindi creare un nuovo ramo dal ramo.0: Listing -8 1 $ git checkout -b NOME_RAMO.0 Usare un nome descrittivo per il proprio ramo (ticket_xxx dove XXX è il numero di ticket è una buona convenzione per i bug). I comandi precedenti porteranno automaticamente sul ramo appena creato (verificare il ramo su cui si sta lavorando con git branch). Lavorare sulla propria patch È possibile lavorare sul codice quanto si vuole e committare tanto quanto si vuole; ma bisogna tenere a mente le seguenti indicazioni: Seguire gli standard del codice (utilizzare git diff --check per controllare i spazi alla fine); Aggiungere test unitari per provare che il bug è stato fissato per mostrare che la funzionalità è effettivamente funzionante; Sforzarsi di non infrangere la retro-compatibilità (se lo si deve fare, provare a fornire un livello di compatibilità che supporti il vecchio modo), le patch che infrangono la retro-compatbilità hanno meno probabilità di essere accettate; Fare commit separati e atomici (utilizzare le funzionalità di git rebase per ottenere uno storico chiaro e pulito); Comprimere i commit irrilevanti, che sistemano solamente gli standard di codice o gli errori di battitura; Non sistemare mai gli standard nel codice esistente, perché rende più difficoltosa la revisione del codice; Scrivere buoni messaggi di commit. Chapter : Inviare una patch 7

8 Si possono verificare gli standard del codice eseguente il seguente script 5 (sorgente 6 ): Listing -9 1 $ cd /path/to/symfony/src $ php symfony-cs-fixer.phar fix. Symfony0Finder Un buon messaggio di commit è composto dal riepilogo nella (prima linea), opzionalmente seguito da una linea vuota e da una descrizione dettagliata. Il riepilogo dovrebbe cominciare con il componente sul quale si sta lavorando posto fra parentesi quadre ([DependencyInjection], [FrameworkBundle],...). Utilizzare un verbo (fixed..., added...,...) per iniziare e non utilizzare il punto finale. Preparare la propria patch Quando la proprià patch non riguarda la sistemazione di un bug (quando si aggiunge una nuova caratteristica o se ne cambia una, per esempio), occorre includere quello che segue: Una spiegazione delle modifiche nel file (o nei file) CHANGELOG rilevante; Una spiegazione di come aggiornare un'applicazione esistente, nel file (o nei file) UPGRADE rilevante, se le modifiche infrangono la retro-compatibilità. Passo 3: inviare la propria patch Quando si ritiene la propria patch pronta per l'invio, seguire i passi seguenti. Fare un rebase Prima di inviare una patch, aggiornare il proprio ramo (necessario se passa del tempo tra il checkout e il commit delle nuove funzionalità) Listing $ git checkout master $ git fetch upstream $ git merge upstream/master $ git checkout NOME_RAMO $ git rebase master Sostituire master con.0 se si sta lavorando sulla risoluzione di un bug Quando si esegue il comando rebase, potrebbe essere necessario risolvere conflitti. Il comando git status metterà in mostra i file non ancora uniti (unmerged ). Risolvere tutti i conflitti e continuare con il rebase: Listing Chapter : Inviare una patch 8

9 1 $ git add... # aggiunge file risolti $ git rebase --continue Verificare che tutti i test stiano ancora passando e inviare gli sviluppi nel ramo remoto. Listing -1 1 $ git push origin NOME_RAMO Richiedere un pull Si può ora eseguire una richiesta di pull sul repository symfony/symfony su Github. Si faccia attenzione a puntare la richiesta di pull verso symfony:.0, se si vuole che la risoluzione del bug riceva un pull basato sul ramo.0. Per facilitare il lavoro, includere sempre i componenti modificati nel messaggio di richiesta di pull, come in: Listing [Yaml] pippo pluto [Form] [Validator] [FrameworkBundle] pippo pluto Si prega di usare un titolo con "[WIP]", se la proposta non è ancora completa o se i test sono incompleti o non passano ancora. La descrizione della richiesta di pull deve includere la seguente lista, per assicurare che i contributi siano rivisti senza continui giri di feedback e che quindi possano essere inclusi in Symfony il prima possibile: Listing Bug fix: [yes no] Feature addition: [yes no] Backwards compatibility break: [yes no] Symfony tests pass: [yes no] Fixes the following tickets: [lista separata da virgole di ticket risolti] Todo: [lista di todo in corso] License of the code: MIT Documentation PR: [Riferimento alla PR di documentazione, se presente] Un esempio di proposta potrebbe essere il seguente: Listing Bug fix: no Feature addition: yes Backwards compatibility break: no Symfony tests pass: yes Fixes the following tickets: #1, #43 Todo: - License of the code: MIT Documentation PR: symfony/symfony-docs#13 Nella descrizione della richiesta di pull, dare quanti più dettagli possibile sulle proprie modifiche (non esitare a fornire esempi di codice per illustrare il punto). Se la richiesta di pull aggiunge nuove caratteristiche o ne modifica di esistenti, spiegare le ragioni delle modifiche. La descrizione della richiesta Chapter : Inviare una patch 9

10 di pull aiuta la revisione del codice e serve da riferimento nel momento del merge (la descrizione della richiesta di pull e tutti i commenti associati sono parte del messaggio di commit del merge). Oltre alla richiesta di pull sul codice, si deve inviare anche una richiesta di pull al repository della documentazione 7, per aggiornare la documentazione relativa. Rielaborare una patch Dipendentemente dal riscontro della lista o attraverso la richiesta di pull su Github, potrebbe essere necessario rielaborare la patch. Prima di re-inserire la patch, eseguire il rebase con il ramo master, ma non unire attraverso il merge; e forzare il push nell'origin: Listing $ git rebase -f upstream/master $ git push -f origin NOME_RAMO Quando si fa un push --force, specificare sempre il nome del ramo in modo esplicito, per evitare complicazioni con altri rami del repository (--force dice a git che si vogliono veramente complicare le cose, quindi va usato con cautela). Spesso, i moderatori richiederanno una compressione dei commit. Questo vuol dire che si convertiranno molti commit in uno solo. Per farlo, usare il comando rebase: Listing $ git rebase -i HEAD~3 $ git push -f origin NOME_RAMO Il numero 3 deve essere uguale al numero di commit nel proprio ramo. Dopo aver scritto questo comando, si aprirà un programma di modifica, con una lista di commit: Listing pick 1a31be6 primo commit pick 7fc64b4 secondo commit pick 7d33018 terzo commit Per unificare tutti i commit nel primo, rimuovere la parola "pick" prima del secondo e dell'ultimo commit e sostituirla con la parola "squash", o anche solo "s". Quando si salva, git inizierà il rebase e, in caso di successo, chiederà di modificare il messaggio di commit, che come predefinito è una lista di messaggi di commit di tutti i commit. Dopo aver finito, eseguire il push. Per fare in modo che il proprio ramo sia automaticamente testato, si può aggiungere il proprio fork a travis-ci.org 8. Basta entrare con l'account usato su github.com e e abilitare un singolo switch, per i test automatici. Nella propria richiesta di pull, invece di specificare "Symfony tests pass: [yes no]", si può collegare l'icona di stato di travis-ci.org 9. Per maggiori dettagli, vedere travis-ci.org Getting Started Guide 10. Lo si può fare in modo facile, cliccando sull'icona della chiave inglese nella pagina del build di Travis. Prima selezionare il proprio ramo, quindi copiare il codice markdown nella descrizione della propria richiesta di pull Chapter : Inviare una patch 10

11 Chapter 3 Segnalazione di un problema di sicurezza Si è trovato un problema di sicurezza in Symfony? Non utilizzare la lista o il tracker. Tutte le questioni di sicurezza devono essere inviate a security [at] symfony-project.com. Le inviate a questo indirizzo verranno inoltrate al team di sviluppo principale di Symfony. Per ogni report, prima si cercherà di confermare la vulnerabilità. Quando confermata, il team di sviluppo lavorerà a una soluzione seguendo questi passi: 1. Inviare un riconoscimento al segnalatore;. Lavorare su una patch; 3. Scrivere un post che descriva la vulnerabilità, i possibili exploit e come aggiornare le applicazioni afflitte; 4. Applicare la patch a tutte le versioni di Symfony in manutenzione; 5. Pubblicare il post sul blog ufficiale di Symfony. Nel periodo in cui si lavora alla risoluzione della patch, si prega di non rivelare pubblicamente il problema. Chapter 3: Segnalazione di un problema di sicurezza 11

12 Chapter 4 Eseguire i test di Symfony Prima di inviare una patch, occorre eseguire tutti i test di Symfony, per assicurarsi di non aver rotto nulla. PHPUnit Per eseguire i test di Symfony, installare 1 prima PHPUnit o successivi. Listing $ pear config-set auto_discover 1 $ pear install pear.phpunit.de/phpunit Dipendenze (opzionali) Per eseguire tutti i test, inclusi quelli che hanno dipendenze esterne, Symfony deve poterli scaricare. Per impostazione predefinita, sono auto-caricati dalla cartella vendor/ (vedere autoload.php.dist). I test necessitano delle seguenti librerie di terze parti: Doctrine Swiftmailer Twig Monolog Per installarle tutte, eseguire lo script vendors: Listing 4-1 $ php vendors.php install 1. Chapter 4: Eseguire i test di Symfony 1

13 Si noti che lo script ha bisogno di tempo per terminare. Dopo l'installazione, si possono aggiornare i venditori alle loro ultime versioni, con il comando seguente: Listing $ php vendors.php update Esecuzione Prima di tutto, aggiornare i venditori (vedere sopra). Quindi, eseguire i test dalla cartella radice di Symfony, con il comando seguente: Listing $ phpunit L'output dovrebbe mostrare OK. Altrimenti, occorre appurare quello che si è verificato e se i test sono rotti per colpa di una propria modifica. Se si vuole testare un singolo componente, scriverne il percorso dopo il comando phpunit, p.e.: Listing $ phpunit src/symfony/component/finder/ Eseguire i test prima di applicare le proprie modifiche, per assicurarsi che girino correttamente con la propria configurazione. Copertura del codice Se si aggiunge una nuova caratteristica, occorre anche verificare la copertura del codice, usando l'opzione coverage-html: Listing $ phpunit --coverage-html=cov/ Verificare la copertura del codice, aprendo la pagina generata cov/index.html in un browser. La copertura del codice funziona solo con XDebug abilitato e tutte le dipendenze installate. Chapter 4: Eseguire i test di Symfony 13

14 Chapter 5 Standard del codice Contribuendo al codice di Symfony, bisogna seguire i suoi standard. Per farla breve, ecco una regola d'oro: imitare il codice esistente di Symfony. La maggior parte dei bundle e delle librerie open source usati da Symfony segue le stesse linee guida. Ricordare che il vantaggio principale degli standard è che ogni pezzo di codice sembra familiare, non è che questo o quello siano più o meno leggibili. Symfony segue gli standard definiti nei documenti PSR-0 1, PSR-1 e PSR- 3. Poiché un'immagine (o un po' di codice) vale più di mille parole, ecco un breve esempio contenente la maggior parte delle caratteristiche descritte sotto: 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; /** string $dummy Una descrizione del parametro Chapter 5: Standard del codice 14

15 } */ public function construct($dummy) { $this->foobar = $this->transform($dummy); } /** string $dummy Una descrizione del parametro string null Input trasformato */ private function transformtext($dummy, $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; Struttura Aggiungere un singolo spazio dopo ogni virgola delimitatrice; Aggiungere un singolo spazio intorno agli operatori (==, &&,...); Aggiungere una riga vuota prima delle istruzioni return, a meno che non siano soli dentro una struttura di controllo (come un if); Usare le parentesi graffe per le strutture di controllo, indipendentemente dal numero di istruzioni contenute; Definire una classe per file (non si applica a classi private di helper che non devono essere istanziate dall'esterno e quindi esulano dallo standard PSR-0); Dichiarare le proprietà di una classe prima dei metodi; Dichiarare prima i metodi pubblici, poi quelli protetti e infine quelli privati; Convenzioni sui nomi Usare camelcase, non i trattini bassi, per nomi di variabili, di funzioni e di metodi; Usare i trattini bassi per nomi di opzioni e parametri; Usare gli spazi dei nomi per tutte le classi; Aggiungere il suffisso Interface alle interfacce; Usare caratteri alfanumerici e trattini bassi per i nomi di file; Non dimenticare di dare un'occhiata al documento più prolisso sulle Convenzioni, per considerazioni più soggettive sulla nomenclatura. Chapter 5: Standard del codice 15

16 Documentazione Aggiungere blocchi PHPDoc per ogni classe, metodo e funzione; Omettere il se il metodo non restituisce nulla; Le non sono usate. Licenza Symfony è rilasciato sotto licenza MIT e il blocco della licenza deve essere presente in cima a ogni file PHP, prima dello spazio dei nomi. Chapter 5: Standard del codice 16

17 Chapter 6 Convenzioni La documentazione Standard del codice descrive gli standard del codice per i progetti Symfony e per i bundle interni e di terze parti. Tale documento descrive gli standard e le convenzioni del codice utilizzate nel nucleo del framework per renderlo più coerente e prevedibile. L'utilizzo nel proprio codice è incoraggiato, ma non obbligatorio. Nomi dei metodi Quando un oggetto ha molte relazioni "principali" correlate a "cose" (oggetti, parametri,...) i nomi dei metodi sono normalizzati in: get() set() has() all() replace() remove() clear() isempty() add() register() count() keys() L'utilizzo di questi metodi sono permessi solo quando è chiaro che si tratti di una relazione principale: un CookieJar ha molti oggetti Cookie; un servizio Container ha molti servizi e molti parametri (come servizi nelle relazioni principali, quindi si usa la convenzione); una Console di Input ha molti argomenti e molte opzioni. Non c'e una relazione principalethere is no "main" e quindi questa convezione non è applicata Per le relazioni per le quali non si può applicare la convenzione, bisogna invece seguire i seguenti metodi (dove XXX è il nome della cosa relazionata ): Chapter 6: Convenzioni 17

18 Relazione principale get() set() n/d has() all() replace() remove() clear() isempty() add() register() count() keys() Altre relazioni getxxx() setxxx() replacexxx() hasxxx() getxxxs() setxxxs() removexxx() clearxxx() isemptyxxx() addxxx() registerxxx() countxxx() n/d Pur essendo "setxxx" e "replacexxx" molto simili, c'e una differenza: "setxxx" può sostituire o aggiungere nuovi elementi alla relazione. A "replacexxx", invece, è espressamente vietato aggiungere nuove elementi, ma la maggior parte solleva un'eccezione in questi casi. Chapter 6: Convenzioni 18

19 Chapter 7 Licenza di Symfony Symfony è distribuito sotto licenza MIT. Secondo Wikipedia 1 : "È una licenza permissiva, cioè permette il riutilizzo nel software proprietario sotto la condizione che la licenza sia distribuita con tale software. È anche una licenza GPLcompatibile, cioè la GPL permette di combinare e ridistribuire tale software con altro che usa la Licenza MIT." La licenza 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: Licenza di Symfony 19

20 Chapter 8 Contribuire alla documentazione La documentazione è importante tanto quanto il codice. E segue esattamente gli stessi principi: DRY, test, facilità di manutenzione, estensibilità, ottimizzazione e refactoring, solo per nominarne alcuni. E certamente la documentazione ha bug, errori di battitura, difficoltà di lettura dei tutorial e molto altro. Contribuire Prima di contribuire, è necessario famigliarizzare con il linguaggio di markup usato per la documentazione. La documentazione di Symfony è ospitata da GitHub: Listing Se si vuole inviare una patch, fare un fork 1 del repository ufficiale su GitHub e fare un clone: Listing 8-1 git://github.com/symfony/symfony-docs.git A meno di non documentare una caratteristica aggiunta in Symfony.1, le modifiche vanno basate sul ramo.0, non sul ramo master. Per poterlo fare, eseguire un checkout del ramo.0 prima del prossimo passo: Listing $ git checkout.0 Quindi, creare un ramo dedicato per le proprie modifiche (per questioni organizzative): Listing $ git checkout -b miglioramenti_di_pippo_e_pluto Si possono ora eseguire le proprie modifiche in tale ramo. Quando si ha finito, fare il push di quest ramo nel proprio fork su GitHub e richiedere un pull. La richiesta di pull sarà tra il proprio ramo miglioramenti_di_pippo_e_pluto e il ramo master di symfony-docs Chapter 8: Contribuire alla documentazione 0

21 ../../_images/docs-pull-request.png Se le proprie modifiche sono basate sul ramo.0, occorre seguire il collegamento di modifica del commit e cambiare il ramo base GitHub spiega l'argomento in modo dettagliato, su richieste di pull. La documentazione di Symfony è rilasciata sotto licenza Creative Commons Attribuzione - Condividi allo stesso modo 3.0 Unported. Le modifiche appaiono sul sito symfony.com website non oltre 15 minuti dopo il merge della richiesta di pull nella documentazione. Si può verificare se le proprie modifiche non abbiano introdotto problemi di markup, guardando la pagina Errori di build della documentazione 3 (aggiornata ogni notte alle 3, quando il server ricostruisce la documentazione). Segnalare una problematica Il modo più semplice di contribuire è segnalando una problematica: un errore di battitura, un errore grammaticale, un bug nel codice di esempio, e così via Passi: Segnalare un bug attraverso il bug Tracker; (opzionale) Inviare una patch. Traduzione Leggere la documentazione apposita Chapter 8: Contribuire alla documentazione 1

22 Chapter 9 Formato della documentazione La documentazione di Symfony utilizza restructuredtext 1, che usa come linguaggio di markup Sphinx per la generazione dell'output (HTML, PDF,...). restructuredtext restructuredtext "è un sistema di analisi e una sintassi a marcatori facilmente leggibile, in testo semplice e WYSIWYG". Si può imparare di più su questa sintassi leggendo i documenti 3 di Symfony oppure leggendo restructuredtext Primer 4 nel sito web di Sphinx. Se si ha dimestichezza con Markdown, bisogna fare attenzione alle cose simili, ma differenti: Le liste cominciano all'inizio della riga (non hanno bisogno di indentazione) I blocchi di codice utilizzano i doppi apici (``come questi``). Sphinx Sphinx è un sistema di compilazione che aggiunge alcuni piacevoli strumenti per creare documentazione da documenti restructuredtext. Come tale, aggiunge nuove direttive e interpreta ruoli di testo definiti nel markup 5 standard rest. Colorazione della sintassi Tutti i blocchi di codice utilizzano PHP come linguaggio predefinito. È possibile cambiarlo con la direttiva code-block: Listing Chapter 9: Formato della documentazione

23 1 3.. code-block:: yaml { foo: bar, bar: { foo: bar, bar: baz } } Se il proprio codice PHP comincia con <?php, allora si avrà bisogno di utilizzare html+php come pseudolinguaggio: Listing code-block:: html+php <?php echo $this->foobar();?> La lista dei linguaggi supportati è disponibile nel sito di Pygments 6. Blocchi di configurazione Ogni volta che si mostra una configurazione, per mostrarla in tutti i formati supportati,bisogna utilizzare la direttiva configuration-block (PHP, YAML e XML): Listing configuration-block::.. code-block:: yaml # Configurazione in YAML.. code-block:: xml <!-- Configurazione in XML //-->.. code-block:: php // Configurazione in PHP Il precedente snippet rest mostra un blocco come di seguito: Listing # Configurazione in YAML Ecco la lista dei formati attualmente supportati: Formato markup html xml php yaml jinja html+jinja Mostrato HTML XML PHP YAML Twig Twig 6. Chapter 9: Formato della documentazione 3

24 Formato markup jinja+html php+html html+php ini php-annotations Mostrato Twig PHP PHP INI Annotazioni Test della documentazione Per fare un test della documentazione, prima di un commit: Installare Sphinx 7 ; Eseguire la preparazione rapida di Sphinx 8 ; Installare l'estensione configuration-block di Sphinx (vedere sotto); Eseguire make html e controllare l'html generato nella cartella build. Installare l'estensione configuration-block di Sphinx Scaricare l'estensione dal repository configuration-block 9 Copiare il file configurationblock.py nella cartella _exts della propria cartella dei sorgenti (in cui si trova conf.py) Aggiungere le righe seguenti al file conf.py: Listing #... sys.path.append(os.path.abspath('_exts')) # aggiunge PhpLexer from sphinx.highlighting import lexers from pygments.lexers.web import PhpLexer #... # aggiunge le estensioni alla lista di estensioni extensions = [..., 'sensio.sphinx.refinclude', 'sensio.sphinx.configurationblock', 'sensio.sphinx.phpcode'] # abilita la colorazione per il codice PHP non compreso tra ``<?php...?>`` lexers['php'] = PhpLexer(startinline=True) lexers['php-annotations'] = PhpLexer(startinline=True) # usa PHP come dominio primario primary_domain = 'php' # imposta url per collegamenti alle API api_url = ' Chapter 9: Formato della documentazione 4