👍🎉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.
Non voglio leggere tutta questa roba, ho solo una domanda!!!
- Lavorare sui Repository
- Segnalare Bug
- Suggerire miglioramenti
- Il tuo primo contributo
- Pull Requests
- Altri tipi di Contributo
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à.
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].
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.
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
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.
Quando intendi collaborare ad un progetto presente nell'organizzazione FIUP in Github, il modo migliore è:
- Individuare il repository corretto.
- Fare un fork del repository, cliccando il pulsante "Fork" nell'angolo in alto a destra.
- Clonare il repository forkato, possibilemente via SSH usando il comando
git clone link_del_repository_forkato
. - Aggiungere le proprie modifiche.
- 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.
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.
- 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
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.
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.
- 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.
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.
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.
- 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
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].
- 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
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.
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.
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.
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. |
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 ). |
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. |
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.
Questo documento è ispirato alle linee guida per contribuire al progetto Atom.