CONTRIBUTING.md

Contribuire al FIUP

👍🎉Innanzi tutto, grazie per dedicare del tempo a contribuire! 🎉👍

Le seguenti sono delle regole e delle linee guida per contribuire al FIUP e ai progetti correlati, ospitati nell'Organizzazione FIUP su GitHub.

Queste regole comuni vengono applicate per ciascun repository dell'organizzazione ma possono essere facilmente estese o adattate al singolo. Assicurati sempre di dare un'occhiata al file CONTRIBUTING.md del singolo repository, in quanto potrebbe includere informazioni aggiuntive.

Se avete suggerimenti su come migliorare queste norme e le linee guida associate, sentitevi liberi di proporre cambiamenti a questo documento tramite pull request.

Indice dei contenuti

FIUP

Codice di Condotta

Non voglio leggere tutta questa roba, ho solo una domanda!!!

Come posso contribuire?

• Lavorare sui Repository
• Segnalare Bug
• Suggerire miglioramenti
• Il tuo primo contributo
• Pull Requests
• Altri tipi di Contributo

Stili

• Messaggi Git Commit
• Stile del codice
• Stile della documentazione

Note Aggiuntive

• Etichette per le Issue e Pull Request
• Licenze usate

FIUP

Il FIUP (Futuri Informatici dell'Università di Padova) è un'organizzazione senza scopo di lucro aperta a studenti, docenti e personale dei corsi di Laurea Triennale e Magistrale in Informatica presso la Scuola di Scienze dell'Università degli Studi di Padova. Al momento è solo un'organizzazione gestita prevalentemente da studenti volontari, non è un'associazione ufficialmente riconosciuta dall'università.

Codice di Condotta

Tutti i progetti e gli spazi FIUP adottano lo stesso Codice di Condotta - Patto del contributore. Partecipando al FIUP, dichiari implicitamente di accettare e aderire a questo Codice di Condotta. Per favore segnalate comportamenti in violazione con il Codice di Condotta all'indirizzo [email protected].

Non voglio leggere tutta questa roba, ho solo una domanda!!!

Nota: Per favore non aprire una issue se hai solo una domanda. Puoi trovare più facilmente una risposta usando le risorse elencate in seguito.

Per qualsiasi dubbio o domanda chiedi nel gruppo telegram del FIUP dove la comunità è più attiva e saprà esserti d'aiuto.

Come posso contribuire?

Puoi contribuire ai repository su GitHub, alle attività online e offline del FIUP o semplicemente aiutando altri utenti e caricando i tuoi appunti. Per ulteriori informazioni consulta la sezione Altri tipi di contributo

Lavorare sui repository

Creare un nuovo repository

Per agevolare la creazione dei file CONTRIBUTING abbiamo creato dei template facilmente adattabili da includere in tutti i repository.

Per creare un nuovo repository:

• Crea un nuovo repository all'interno dell'organizzazione FIUP in GitHub
• Esegui un clone in locale del repository, possibilmente via SSH usando il comando git clone link_del_repository
• Copia la cartella docs del repository Getting_Started dentro alla directory principale del tuo repository.
• Adatta i template contenuti nella cartella docs in base alle esigenze del tuo repository, in particolare:
  • Imposta un README, puoi usare il README template.
  • E' sconsigliato modificare i file ISSUE_TEMPLATE e PULL_REQUEST_TEMPLATE in quanto potrebbero entrare in conflitto con le linee guida generali per contribuire.
  • Imposta il file CONTRIBUTING con le linee guida specifiche per contribuire al tuo repository, adattando il CONTRIBUTING template.
  • Assicurati che nei file README e CONTRIBUTING sia presente un link al nostro Code of Conduct. Creando un nuovo repository dichiari di accettare e di rispettare il nostro codice di condotta.
  • Assicurati di avere un file LICENSE che specifica la licenza del tuo repository. Cerca di usare licenze libere. I repository del FIUP senza licenze non sono da considerarsi software proprietario. Per ulteriori informazioni consulta la nostra policy sulle licenze.
• Effettua le modifiche che ritieni necessarie al tuo repository, fai una commit e una push.
• Complimenti, il tuo repository è impostato e fa ora parte del FIUP.

Collaborare a un repository esistente

Quando intendi collaborare ad un progetto presente nell'organizzazione FIUP in Github, il modo migliore è:

1. Individuare il repository corretto.
2. Fare un fork del repository, cliccando il pulsante "Fork" nell'angolo in alto a destra.
3. Clonare il repository forkato, possibilemente via SSH usando il comando git clone link_del_repository_forkato.
4. Aggiungere le proprie modifiche.
5. Inviare una Pull Request al repository originale.

Se la Pull Request verrà accettata da un manutentore, il tutto andrà a buon fine e il contributo sarà aggiunto.

Segnalare Bug

Seguire queste linee guida aiuta i manutentori e la comunità a capire più facilmente il problema.

Prima di inviare una segnalazione sui bug, per favore controlla questa lista in quanto potresti scoprire che non necessiti di segnarlo. Mentre stai creando una segnalazione, per favore includi quanti più dettagli possibile. Puoi usare questo template per strutturare le informazioni.

Prima di inviare una segnalazione sui bug

• Fai una ricerca tra le issue in modo da accertarti che il problema non sia già stato segnalato. Se lo è, aggiungi un commento alla issue esistente al posto di aprirne una nuova.

Puoi segnalare bug utilizzando le Issue di GitHub

Come invio una buona segnalazione?

I bug sono tracciati usando le issue di GitHub. Dopo aver individuato un problema, apri una issue nel relativo repository, fornendo le seguenti informazioni.

Esponi il problema e includi il maggior numero di dettagli in modo da aiutare i manutentori a riprodurlo.

• Usa un titolo chiaro e descrittivo per la issue, identificando il problema.

• Descrivi precisamente i passi per riprodurre il problema con quanti più dettagli possibile. Quando spieghi i passi, non dire solo cosa hai fatto, ma spiega come lo hai fatto. Per esempio, se hai compilato un sorgente LaTeX, spiega se hai usato uno script o un IDE.

• Fornisci esempi espliciti per riprodurre i passi. Puoi includere link a file o a progetti su GitHub, o copia incollare parti di codice in questi esempi. Se includi spezzoni di codice nelle issues usa i blocchi di codice in Markdown.

• Descrivi il comportamento osservato dopo aver seguito i passi specifica esattamente qual è il problema e il suo comportamento.

• Spiega quale sarebbe il comportamento corretto secondo te e perché

• Includi screenshots che mostrino e descrivano i passi seguiti e possano mostrare in modo chiaro il problema.

• Puoi riprodurre costantemente la issue? Se non puoi, fornisci dettagli circa quanto spesso il problema capita e sotto quali condizioni solitamente succede.

Includi dettagli sul tuo ambiente e sulla tua configurazione:

• Qual è il nome e la versione del sistema operativo usato?

• Stai usando una macchina virtuale? Se si, che software usi e che sistemi operativi usi sia per l'host che per il guest?

• Quali altri software stai usando inerentemente il problema? Spiega che compilatore usi e le dipendenze adottate.

Suggerire miglioramenti

Questa sezione ti guiderà su come inviare suggerimenti per migliorare il FIUP e i progetti ad esso correlati. Seguire queste linee guida aiuta i manutentori e la comunità a capire il tuo suggerimento 📝 e a collegarlo ad altri già esistenti 🔎 .

Prima di creare suggerimenti, per favore controlla questa lista in quanto potresti scoprire di non aver bisogno di crearne uno nuovo. Quando suggerisci una miglioria, per favore includi quanti più dettagli possibile. Per agevolarti abbiamo creato un template.

Prima di inviare un suggerimento

• Fai una ricerca tra le issue in modo da accertarti che il suggerimento non sia già stato posto. Se lo è, aggiungi un commento alla issue esistente al posto di aprirne una nuova.

Come posso suggerire una miglioria?

I suggerimenti per migliorare sono tracciati usando le issues di GitHub. Quando hai le idee chiare sulla modifica da proporre, crea una issue sul repository adatto (per inviare suggerimenti generali usa questo repository ) e fornisci le seguenti informazioni:

• Usa un titolo chiaro e descrittivo per la issue che identifica il suggerimento.
• Fornisci una descrizione passo passo della miglioria con quanti più dettagli possibili.
• Fornisci esempi concreti a dimostrazione dei passi. se devi includere codice in questi esempi, usa i blocchi di codice in Markdown.
• Descrivi il comportamento attuale e spiega quale comportamento vorresti e perché.
• Spiega perché questa miglioria sarebbe utile per la maggior parte degli utenti.

Il tuo primo contributo

Non sai dove iniziare a contribuire al FIUP? Potresti iniziare dalle issue etichettate come beginner e/o help-wanted:

• Beginner issues: Issues che riguardano problemi semplici che richiedono un paio di linee di codice e un paio di test.
• Help wanted issues: Issues un po' più impegnative delle beginner.

Entrambe le liste di issues sono ordinate in base al numero totale di commenti. Anche se non è perfetto, il numero di commenti è un misuratore ragionevole dell'impatto che una issue potrà avere.

Pull Requests

• Compila il template
• Non includere i numeri delle issue nel titolo della PR
• Includi screenshots e/o GIF animate nella tua PR se lo ritieni utile.
• Documenta il nuovo codice usando gli Stili della documentazione

Altri tipi di contributo

Per contribuire al FIUP non è necessario essere programmatori esperti. Puoi contribuire in tanti altri modi ad esempio:

• Aiutando gli utenti, rispondendo ai loro dubbi o domande sui canali social in particolare su telegram e facebook.
• Caricando appunti e altri file negli spazi cloud del FIUP, rispettando le regole definite qui.
• Partecipare alle attività offline del FIUP.
• Proporre idee e suggerimenti all'indirizzo [email protected] o secondo le modalità indicate nella sezione Suggerire miglioramenti.
• Candidarsi a manutentore dei repository, o per avere un ruolo attivo nella struttura del FIUP, compilando questo form o via mail all'indirizzo [email protected].

Stili

Messaggi Git Commit

• Usa messaggi chiari e descrittivi delle modifiche apportate ("Fatti cambiamenti vari" non è un buon messaggio)
• Usa preferibilmente la lingua inglese
• Scrivi i messaggi usando il presente e l'imperativo ("Add feature" not "Added feature") ("Move cursor to..." not "Moves cursor to...")
• Limita la prima linea a 72 caratteri o meno
• Nelle linee successive collega liberamente la commit alle issue e alle pull request

Stili del codice

Uno stile del codice standard per molti progetti è essenziale. Per i progetti FIUP, salvo quanto specificato nel file CONTRIBUTING dei singoli repository, non si adotta uno stile standard. Questo permette a chiunque di partecipare liberamente senza troppi problemi. L'importante è che:

• Il codice sia commentato (in italiano o in inglese). Il codice non commentato è scarsamente utile, soprattutto se riguarda esercizi che hanno lo scopo di far capire i procedimenti svolti e le soluzioni adottate.

Stili della documentazione

Anche per la documentazione non adottiamo uno standard preciso. I linguaggi da usare sono preferibilmente HTML, Markdown e LaTeX.

I commenti al codice sono da intendersi come parte integrante della documentazione.

Note aggiuntive

Etichette per le Issues e Pull Request

Questa sezione lista le etichette che usiamo per aiutarci a tener traccia e gestire sia le issues che le pull requests. Molte etichette sono usate in tutti i repositori del FIUP, ma alcune sono specifice di questo repository.

La ricerca di GitHub rende facile usare le etichette per trovare gruppi di issues o pull requests alle quali sei interessato. Per esempio, potresti essere interessato nelle issues aperte di questo repository non ancora controllate. Per aiutarti a trovare issues e pull requests in modo più efficace, ti incoraggiamo a leggere questo approfondimento sui filtri di ricerca, ti aiuterà a scrivere query più mirate.

Le etichette sono raggruppate in base al loro scopo, ma non è richiesto che ogni issue abbia un'etichetta per ciascun gruppo o che una issue non possa avere più di un'etichetta per gruppo.

Per favore, apri una issue in fiup/Getting_Started se hai suggerimenti per nuove etichette. Se noti che alcune etichette non sono presenti nei repository, apri una issue in quel repository.

Tipi di Issue e loro stato

Nome dell'etichetta	Descrizione
beginner	Issue poco complesse adatte a chi contribuisce per le prime volte al FIUP.
blocked	Issue bloccate da altre issue.
bug	Bug noti o segnalazioni circa possibili bug.
duplicate	Issue che sono duplicati di altre, già create in precedenza.
enhancement	Richiesta di nuove feature / miglioramenti, invio di suggerimenti.
feedback	Richiesta di feedback in merito ad un progetto da parte della comunità.
first-timers-only	Issue poco complesse adatte esclusivamente a chi contribuisce per la prima volta al FIUP.
help-wanted	I manutentori del FIUP apprezzerebbero aiuto dalla comunità nel risolvere queste issue.
invalid	Issue non valide (per es. per errori degli utenti).
more-information-needed	Più informazioni devono essere raccolte circa questo problema o richiesta di miglioramenti ad es. i passi per riprodurre il problema).
question	Domande inerenti l'organizzazione FIUP in GitHub. Per altri tipi di domande usare i gruppi social.
wontfix	Il team del FIUP ha deciso di non fixare la issue per il momento per qualche ragione.
wrong-repo	Issue aperta nel repository sbagliato.

Categorie per temi

Nome dell'etichetta	Descrizione
windows	Relative ai problemi su Windows.
linux	Relative ai problemi su Linux.
mac	Relative ai problemi su macOS / iOS.
documentation	Relative a problemi / migliorie alla documentazione.
performance	Relative alle performance.
security	Relative alla sicurezza
ui	Relative alle parti grafiche.
api	Relative alle API.
crash	Relative ai problemi che causano un crash.
git	Relative ai problemi con git (per es. problemi con i file .gitignore).

Etichette per le Pull Request

Nome dell'etichetta	Descrizione
work-in-progress	Pull requests sulle quali si sta ancora lavorando, ulteriori modifiche arriveranno in futuro.
needs-review	Pull requests che necessitano di essere controllate da manutentori del FIUP per aggiornare i progetti.
under-review	Pull request in fase di controllo da parte dei manutentori del FIUP.
requires-changes	Pull request che necessitano cambiamenti dopo essere state controllate, a seguito dei cambiamenti dovranno essere riviste di nuovo.
needs-testing	Pull request che richiedono test manuali.

Licenze usate

Tutto il materiale caricato sugli spazi FIUP, se non esplicitamente rilasciato dall'utente allegando una specifica licenza, è da intendersi rilasciato sotto licenze CC BY-SA 4.0 se si tratta di appunti, esercitazioni, e opere per i quali l’utente che carica dispone dei diritti. Per il codice, salvo quanto diversamente indicato, si intende interamente rilasciato sotto licenza GPLv3.

E’ possibile condividere materiale e codice usando licenze differenti, purché l'utente includa un file "LICENSE" riportante la licenza che desidera utilizzare oppure includa nel materiale stesso dei riferimenti alla licenza stessa. Per incentivare la condivisione e un miglioramento continuo è consigliato evitare licenze chiuse e proprietarie.

Se non si sa che licenza scegliere, si può consultare questo strumento, ulteriori informazioni su come associare una licenza ad un repository, possono essere reperite qui.

Ulteriori riferimenti

Questo documento è ispirato alle linee guida per contribuire al progetto Atom.