FAQ: Contribuire a Sage.

Come posso iniziare a contribuire a Sage?

Il primo passo è usare Sage e incoraggiare i tuoi amici a usare Sage. Se trovi bug o della documentazione poco chiara, per favore riporta i problemi!

Due modi comuni per contribuire a Sage sono scrivere codice sorgente e creare documentazione o tutorial. Alcuni passi in entrambe le direzioni sono descritti di seguito.

Voglio contribuire a Sage. Da dove inizio?

Dai un’occhiata alla guida ufficiale per lo sviluppo di Sage. Come minimo, la lettura del primo capitolo è richiesta per ogni sviluppatore di Sage. Inoltre sii molto attento alle linee guida per trac. Puoi entrare nella lista email sage-devel. Mentre inizi a conoscere la comunità prendi una copia del codice sorgente di Sage e familiarizza con git, un software per il controllo versione.

Il miglior modo per diventare familiare con il processo di sviluppo di Sage è quello di scegliere un ticket dal server trac ed esaminare i cambiamenti proposti in quel ticket. Se vuoi costruire qualcosa, è buona pratica discutere le tue idee sulla lista email sage-devel, in modo che altri sviluppatori abbiano l’opportunità di esprimersi sulle tue idee/proposte. Sono anche aperti a nuove idee, come tutti i matematici dovrebbero essere.

La principale lingua di programmazione per Sage è Python. Alcune parte di Sage potrebbero essere scritte in altre lingue, specialmente le componenti che fanno l’elaborazione numerica più impegnativa, ma la maggior parte delle funzionalità sono realizzate in Python, incluso il codice di collegamento. Un aspetto valido di Python, che Sage eredita, è che è più importante scrivere codice funzionante piuttosto che codice veloce. Del codice veloce è prezioso, ma del codice chiaro e leggibile è importante. Nella comunità matematica i risultati inaccurati sono inaccettabili. La correttezza viene prima dell’ottimizzazione. Nel seguente articolo

  • D. Knuth. Structured Programming with go to Statements. ACM Journal Computing Surveys, 6(4), 1974.

Don Knuth osserva che “dovremmo dimenticarci dell’efficienza di poco conto, diciamo per il 97% del tempo: l’ottimizzazione prematura sta alla radice di ogni male”.

Se non conosci Python dovresti iniziare ad imparare il linguaggio. Un buon posto dove iniziare è il Tutorial Ufficiale per Python e altra documentazione si trova in Documentazione standard di Python. Un altro posto da guardare è al link Dive Into Python di Marc Pilgrim, che può essere veramente d’aiuto su temi specifici come lo sviluppo guidato dai test. Il libro Building Skills in Python di Steven F. Lott è adatto a chiunque sia già a suo agio nel programmare.

Se desideri, puoi iniziare a imparare Python usando Sage. Tuttavia, è utile sapere cosa è semplice Python e quando Sage sta usando la sua “magia”. Ci sono molte cose che funzionano in Python, ma non in Sage e vice versa. Per di più anche quando la sintassi è identica, molti concetti di programmazione sono spiegati più dettagliatamente in risorse focalizzate su Python piuttosto che in risorse centrate su Sage; in quest’ultime, la priorità viene data alla matematica.

Non sono un programmatore. C’è qualche altro modo in cui posso aiutare?

Certo. Come in ogni progetto FOSS ci sono molti modi in cui puoi dare il tuo aiuto nella comunità di Sage e programmare è solo uno di questi.

Molte persone amano scrivere tutorial tecnici. Una delle gioie di farlo è che impari qualcosa di nuovo nel farlo. Allo stesso tempo trasmetti delle conoscenze ai principianti, un’abilità che è utile anche in campi estranei alla stesura di documentazione tecnica. Un aspetto fondamentale della documentazione tecnica è che espone un dato tecnico a dei principianti, pertanto il gergo tecnico dev’essere ridotto al minimo. Darrell Anderson ha scritto alcuni suggerimenti sulla scrittura di documentazione tecnica, il quale consigliamo vivamente.

Per i designer grafici o gli artisti c’è la possibilità di aiutare migliorando l’aspetto del sito di Sage.

Se sai parlare, leggere e scrivere in un’altra lingua, ci sono molti modi in cui il tuo contributo può essere molto prezioso all’intera comunità di Sage. Diciamo che conosci l’italiano. Allora puoi scrivere un tutorial per Sage in italiano, o aiutare a tradurre i tutorial ufficiali di Sage in italiano.

La suddetta è una lista molto breve. Ci sono molti, molti più modi in cui puoi dare il tuo aiuto. Sentiti libero di inviare una email alla mailing list sage-devel per chiedere in quali modi potresti essere d’aiuto, o per suggerire un’idea sul progetto.

Dove posso trovare risorse su Python e Cython?

Ecco una lista incompleta di risorse su Python e Cython. Ulteriori risorse possono essere trovate cercando sul web.

Risorse generali

Tutorial e libri

Articoli e HOWTO

Ci sono delle convenzioni di scrittura del codice sorgente che devo seguire?

Dovresti seguire le convenzioni standard di Python come documentato in PEP 8 e PEP 257. Consulta anche la Guida dello Sviluppo Sage, specialmente il capitolo Convenzioni per scrivere codice sorgente in Sage.

Ho inviato al GitHub Sage repo una correzione molte settimane fa. Perché la state ignorando?

Non stiamo cercando di ignorare la tua correzione. Le persone che lavorano su Sage lo fanno nel loro tempo libero. Con centinaia di ticket aperti aventi un impatto molto variabile sulla comunità di Sage, le persone che ci lavorano devono dedicare il loro tempo e sforzo principalmente a quei ticket che li interessano. A volte potresti essere la sola persona che comprende la tua correzione. In tal caso, ti invitiamo a fare uno sforzo supplementare per rendere l’esaminazione della tua patch il più semplice possibile. Ecco alcuni suggerimenti su come rendere la tua correzione facile da esaminare

  • Hai descritto in modo chiaro il problema che la tua correzione vuole risolvere?

  • Hai fornito ogni informazione di base rilevante al problema che la tua correzione vuole risolvere? Tali informazioni includono link a risorse online e ad articoli, libri, o altro materiale di riferimento.

  • Hai descritto in modo chiaro come la tua correzione risolve il problema in oggetto?

  • Hai descritto chiaramente nella tua correzione come effettuare i test dei cambiamenti?

  • Hai elencato eventuali tickets da cui dipende la tua correzione?

  • Se vi sono più correzioni, hai indicato chiaramente l’ordine in cui devono essere applicate ?

  • La tua correzione segue le convenzioni importanti indicate nella “Guida dello sviluppatore”?

Se la tua correzione non ha la possibilità di essere aggiunta nell’albero dei sorgenti di Sage, non la ignoreremo ma semplicemente chiuderemo il ticket relativo con una spiegazione sul perché non possiamo includerla.

Come e quando posso ricordare alla comunità di Sage una correzione a cui tengo?

Ti suggeriamo di fare uno sforzo ulteriore sul come ricordare alla comunità di Sage una correzione che vuoi venga inclusa nell’albero dei sorgenti di Sage. Potrebbe esserci un prossimo evento “bug squash sprint” o “Sage days” che è in relazione alla tua correzione. Tieni d’occhio le mailing list relative e rispondi educatamente ad ogni scambio di email relativo, spiegando chiaramente perché la tua correzione ha importanza.

Ho scritto del codice sorgente e voglio venga incluso in Sage. Però dopo aver rinominato il mio file a.sage in a.py ho degli errori di sintassi. Devo riscrivere tutto il mio codice in Python anziché in Sage?

La risposta sostanzialmente è sì, ma riscrivere è una parola grossa per ciò che bisogna realmente fare. C’è ben poco da fare dal momento che Sage per lo più segue la sintassi di Python. Le 2 maggiori differenze sono la gestione degli interi (vedi anche il link afterword per maggiori informazioni sul preparser di Sage) e la necessità di importare quello che ti serve.

  • Gestione degli interi: dei fare i seguenti cambiamenti:

    • Notazione per l’elevamento a potenza: In Python ** significa elevamento a potenza e ^ significa “xor”.

    • Se devi restituire un intero all’utente, scrivi return Integer(1) invece di return 1. In Python, 1 è un intero Python (int), e Integer(1) è un intero Sage/Gmp. Inoltre gli Integer sono molto più potenti degli int; ad esempio hanno collegata ad essi l’informazione di primalità e la fattorizzazione.

    • Dovresti anche notare che 2 / 3 non significa più Integer(2) / Integer(3) che restituisce 2/3, ma invece int(2) / int(3), e pertanto restituisce 0 poiché la divisione è intera e trascura il resto. Se stai lavorando con i tipi Integer ma in realtà hai bisogno di eseguire una divisione intera puoi usare Integer(2) // Integer(3).

  • Note sull’importazione: la seconda cosa importante da tenere presente è la necessità di importare tutto ciò di cui hai bisogno. Nel dettaglio, ogni volta che usi una funzione Sage la devi prima importare all’inizio del file. Ad esempio, se hai bisogno di PolynomialRing, dovrai scrivere:

    from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing

    Puoi chiedere a Sage dove il comando per importare PolynomialRing usando:

    sage: import_statements(PolynomialRing)
from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing

    >>> from sage.all import *
>>> import_statements(PolynomialRing)
from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing

    import_statements(PolynomialRing)

    Se questo fallisce, puoi chiedere a Sage dove si trove PolynomialRing usando:

    sage: PolynomialRing.__module__
'sage.rings.polynomial.polynomial_ring_constructor'

    >>> from sage.all import *
>>> PolynomialRing.__module__
'sage.rings.polynomial.polynomial_ring_constructor'

    PolynomialRing.__module__

    Questo corrisponde anche al percorso, che inizia dopo site-packages, restituito da Sage quando richiami l’help su PolynomialRing. A d esempio se scrivi PolynomialRing? otterrai:

    Type:    function
[...]
File:    /path_to_sage_root/sage/local/lib/python3.7/site-packages/sage/rings/polynomial/polynomial_ring_constructor.py
[...]