Skip to content

Latest commit

 

History

History
264 lines (176 loc) · 15.2 KB

CONTRIBUTING-it.md

File metadata and controls

264 lines (176 loc) · 15.2 KB
Raw

Leggilo in altre lingue

Accordo di Licenza

Contribuendo tu accetti alla LICENZA di questa repository.

Codice di Comportamento del Collaboratore

I collaboratori accettano di rispettare il Codice di Comportamento di questa repository. (translations)

In breve

  1. "Un link per scaricare facilmente un libro" non è sempre un link per scaricare un libro gratuito. Per favore contribuisci solo con contenuti gratuiti. Assicurati che sia gratuito. Non accettiamo link a pagine che richiedono email funzionanti per ottenere il libro, ma diamo il benvenuto agli annunci che li richiedono.

  2. Non devi conoscere Git: se trovi qualcosa di interessante che che non è ancora in questa repo, apri un Issue con il link della risorsa.

    • Se conosci Git, forka questa repository e crea una Pull Request (PR).

  3. Abbiamo 6 tipi di liste. Scegli quella giusta:

    • Libri : PDF, HTML, ePub, gitbook.io, una Git repo, etc.
    • Corsi : Un corso è del materiale gratuito che non è un libro. Questo è un corso.
    • Tutorial Interattivi : Un sito interattivo permette all'utente di scrivere codice o comandi e analizzarne il risultato. esempi: Try Haskell, Try GitHub.
    • Playgrounds : Sono siti, giochi o applicazioni online ed interattive per imparare a programmare. Scrivi, compila (o esegui) e condividi codice. I playgrounds spesso ti permettono di forkare una repository e sporcarti le mani "giocando" con il codice.
    • Podcasts e Screencasts : Podcasts and screencasts.
    • Set di problemi & Programmazione competitiva : Un sito o software che ti permette di valutare le tue skills da programmatore risolvendo problemi semplici o complessi, con o senza la revisione del codice, con o senza la comparazione del risultato con gli altri utenti.

  4. Assicurati di seguire le linee guida qui sotto e rispettare la formattazione Markdown dei file.

  5. GitHub Actions avvierà dei test per assicurarsi che le tue liste siano ordinate alfabeticamente e formattate correttamente. Assicurati che i tuoi cambiamenti passino il test.

Linee guida

  • assicurati che il libro sia gratuito. Controlla più volte se necessario. Commentare nella PR il perché pensi che il libro sia gratuito aiuta gli admin.
  • non accettiamo file hostati su Google Drive, Dropbox, Mega, Scribd, Issuu e altre piattaforme simili per l'upload dei file
  • inserisci i link ordinandoli alfabeticamente, come descritto sotto.
  • usa il link più "autorevole" per segnalare la risorsa (significa che il sito web dell'autore è migliore del sito web dell'editore, che è migliore di un sito web di terze parti)
    • nessun servizio di file hosting (questo include (ma non è limitato a) link di Dropbox e Google Drive)
  • preferisci sempre un link https rispetto ad un http -- purché si trovino sullo stesso dominio e contengano lo stesso contenuto
  • sul dominio di root, elimina il trailing slash (lo slash finale): http://example.com invece di http://example.com/
  • preferisci sempre link più corti: http://example.com/dir/ è migliore di http://example.com/dir/index.html
    • niente link accorciati
  • generalmente preferisci il link "current" rispetto al link "version": http://example.com/dir/book/current/ è migliore di http://example.com/dir/book/v1.0.0/index.html
  • se un link ha un certificato scaduto/certificato auto-firmato/problemi di SSL o di qualsiasi altro tipo:
    1. sostituiscilo con la controparte in http se possibile (perché accettare eccezione può essere complicato sui dispositivi mobile).
    2. lascialo se non è disponibile alcuna versione in http ma la versione https è ancora accessibile aggiungendo l'eccezione al browser o ignorando l'avviso.
    3. rimuovilo altrimenti.
  • se un link esiste in più formati, aggiungi un link separato con una nota riguardante il formato
  • se una risorsa è presente in posti differenti su internet
    • usa il link più "autorevole" per segnalare la risorsa (significa che il sito web dell'autore è migliore del sito web dell'editore, che è migliore di un sito web di terze parti)
    • se reindirizzano a edizioni differenti e tu credi che queste edizioni siano abbastanza diverse tra loro da valere la pena di essere tenute, aggiungi un link separato con una nota riguardante ogni edizione (guarda Issue #2353 per contribuire alla discussione sulla formattazione).
  • preferisci gli atomic commits (un commit per aggiunta/modifica/eliminazione) rispetto ai grandi commit. Non c'è bisogno di raggruppare i commit per inviarli in una sola PR. (Non applichiamo mai questa regola, è solo per comodità dei moderatori)
  • se il libro è più vecchio, includi la data di pubblicazione assieme al titolo.
  • includi il nome o i nomi degli autori se è il caso. Puoi accorciare il nome degli autori con "et al.".
  • se il libro non è ancora finito, e ci stanno ancora lavorando su, aggiungi "in process", come descritto qui sotto. Seleziona sempre l'ultima versione disponibile in questi siti.
  • se una risorsa è archiviata usando la Wayback Machine di Internet Archive (o simili), aggiungi la notazione "archived", come descritto qui sotto. La versione migliore da utilizzare è quella più recente/completa.
  • se è richiesto un indirizzo email o un account per poter scaricare il libro, aggiungilo tra parentesi, esempio: (email address *requested*, not required).

Formattazione

  • Tutte le liste sono file .md. Prova ad imparare la sintassi Markdown. È semplice!
  • Tutte le liste iniziano con un Index. L'idea è di elencare e collegare tutte le sezioni e sottosezioni lì. Mantienila in ordine alfabetico.
  • Le sezioni utilizzano il livello 3 di heading (###), e le sottosezioni utilizzano il livello 4 di heading (####).

L'idea è di avere:

  • 2 linee vuote tra l'ultimo link e la nuova sezione.
  • 1 linea vuota tra il titolo e il primo link della sezione.
  • 0 linee vuote tra due link.
  • 1 linea vuota alla fine di ogni file .md.

Esempi:

[...]
* [An Awesome Book](http://example.com/example.html)
                                (linea vuota)
                                (linea vuota)
### Esempio
                                (linea vuota)
* [Another Awesome Book](http://example.com/book.html)
* [Some Other Book](http://example.com/other.html)

  • Non mettere uno spazio tra ] e (:

    SCORRETTO: * [Another Awesome Book] (http://example.com/book.html)
CORRETTO : * [Another Awesome Book](http://example.com/book.html)

  • Se includi gli autori, usa - (un trattino circondato da spazi singoli):

    SCORRETTO: * [Another Awesome Book](http://example.com/book.html)- John Doe
CORRETTO : * [Another Awesome Book](http://example.com/book.html) - John Doe

  • Metti uno spazio tra il link e il formato:

    SCORRETTO: * [A Very Awesome Book](https://example.org/book.pdf)(PDF)
CORRETTO : * [A Very Awesome Book](https://example.org/book.pdf) (PDF)

  • Gli autori vanno prima del formato:

    SCORRETTO: * [A Very Awesome Book](https://example.org/book.pdf)- (PDF) Jane Roe
CORRETTO : * [A Very Awesome Book](https://example.org/book.pdf) - Jane Roe (PDF)

  • Formati multipli:

    SCORRETTO: * [Another Awesome Book](http://example.com/)- John Doe (HTML)
SCORRETTO: * [Another Awesome Book](https://downloads.example.org/book.html)- John Doe (download site)
CORRETTO : * [Another Awesome Book](http://example.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html)

  • Includi l'anno di pubblicazione nel titolo per i libri più vecchi:

    SCORRETTO: * [A Very Awesome Book](https://example.org/book.html) - Jane Roe - 1970
CORRETTO : * [A Very Awesome Book (1970)](https://example.org/book.html) - Jane Roe

  • Libri in sviluppo:

    CORRETTO : * [Will Be An Awesome Book Soon](http://example.com/book2.html) - John Doe (HTML) *(:construction: in process)*

  • Link archiviato:

    CORRETTO : * [A Way-backed Interesting Book](https://web.archive.org/web/20211016123456/http://example.com/) - John Doe (HTML) *(:card_file_box: archived)*

Ordinamento alfabetico

  • Quando ci sono più titoli che iniziano con la stessa lettera devi ordinarli in base alla seconda, e così via. Per esempio: aa viene prima di ab.
  • one two viene prima di onetwo

Se vedi un link messo male, controlla gli errori dati dal linter per scoprire quali linee devi scambiare.

Note

Mentre le basi sono relativamente semplici, c'è una notevole differenza tra le risorse che inseriamo nelle liste. Qui ci sono alcuni appunti su come affrontiamo queste diversità.

Metadata

I nostri elenchi forniscono un set minimo di metadati: titoli, URLs, autori, piattaforme e note di accesso.

Titoli
  • Non inventiamo i titoli. Cerchiamo di prendere i titoli dalla risorsa originale; i contributori sono invitati a non inventare titoli o usarli editorialmente se questo può essere evitato. Un'eccezione è per i libri più vecchi; se sono principalmente di interesse storico, l'anno tra parentesi inserito nel titolo aiuta gli utenti a capire se sono interessati a quella risorsa.
  • Niente titoli completamente in MAIUSCOLO. Di solito il title case è appropriato, ma in caso di dubbio usa le maiuscole utilizzate nella fonte.
  • Niente emoji.
URLs
  • Non per mettiamo di rimpicciolire il link con gli appositi strumenti.
  • Il codice di tracciamento deve essere rimosso dall'URL.
  • Gli URL internazionali devono essere evitati. Le barre del browser in genere li rendono in Unicode, ma usa copia e incolla, per favore.
  • I link sicuri (https) sono preferibili al posto dei link non sicuri (http), dove l'HTTPS è stato implementato.
  • Non ci piacciono gli URL che reindirizzano in una pagina che non hosta la risorsa, ma invece reindirizza altrove.
Autori

  • Vogliamo dare i crediti agli autori ove appropriato, anche ai traduttori!

  • Per i lavori tradotti, l'autore originale dovrebbe essere incluso. Consigliamo di usare MARC relators per accreditare autori diversi dal creatore, per esempio:

    * [Un libro tradotto](http://example.com/book-it.html) - John Doe, `trl.:` Mike The Translator

    qui, l'annotazione trl.: usa il codice MARC relativo ai "traduttori".

  • Usa l virgola , per separare ogni elemento nella lista degli autori

  • Puoi accorciare la lista degli autori scrivendo "et al." (e altri).

  • Non permettiamo collegamenti per gli autori.

  • Per le compilation o remix, il "creatore" potrebbe aver bisogno di una descrizione. Ad esempio, i libri "GoalKicker" o "RIP Tutorial" sono accreditati come "Compiled from StackOverflow documentation".

Piattaforme e note di accesso
  • Corsi. Specialmente per la nostra liste dei corsi, la piattaforma è una parte importante della descrizione. Questo perché le varie piattaforme di corsi hanno diverse affordance e metodi di accesso. Mentre solitamente i libri non hanno bisogno di un account per essere letti, molte piattaforme di corsi ne hanno bisogno. Esempi di piattaforme di corsi sono Coursera, EdX, Udacity e Udemy. Quando un corso dipende dalla piattaforma, il suo nome dovrebbe essere incluso tra parentesi.
  • YouTube. Abbiamo molti corsi che consistono in playlist di YouTube. Non consideriamo YouTube come piattaforma, cerchiamo di inserire il creatore del corso, che è spesso una sotto-piattaforma.
  • Video YouTube. Solitamente non accettiamo singoli video YouTube, a meno che non siano più lunghi di un'ora e che siano strutturati come un corso o un tutorial.
  • Leanpub. Leanpub ospita libri con varie modalità di accesso. Alcune volte i libri possono essere letti senza l'obbligo di registrazione; alcune volte è necessario creare un account gratuito su Leanpub. Data la qualità dei libri e la commistione e fluidità dei modelli di accesso Leanpub, consentiamo di elencare questi ultimi con la nota di accesso *(Leanpub account or valid email requested)*.

Generi

La prima regola è decidere a quale lista appartiene di più una risorsa. Se si definisce un libro, allora forse è un libro.

Generi che non accettiamo

Essendo che internet è vasto, noi non accettiamo:

  • blog
  • blog posts
  • articoli
  • siti web (ad eccezione di quelli che ospitano MOLTI articoli che elenchiamo).
  • video che non sono corsi o screencasts.
  • capitoli dei libri
  • teaser dei libri
  • IRC o canali Telegram
  • Slacks o newsletter

I nostri elenchi di programmi competitivi non sono così severi riguardo a queste esclusioni. L'ambito del repo è determinato dalla comunità; se desideri suggerire una modifica o un'aggiunta all'ambito, utilizza un problema per suggerire.

Libri vs. Altro

Non siamo così esigenti riguardo al libro. Ecco alcuni attributi che indicano che una risorsa è un libro:

  • ha un ISBN (International Standard Book Number)
  • ha una tabella dei contenuti
  • è offerta una versione scaricabile, specialmente ePub
  • ha un'editizone
  • non dipende da contenuti interattivi o video
  • cerca di coprire in modo completo l'argomento
  • è autonomo

Ci sono molti libri che abbiamo aggiunto che però non hanno questi attributi; dipende dal contesto.

Libri vs. Corsi

A volte questi possono essere difficili da distinguere!

I corsi hanno spesso libri di testo associati, che elencheremo nei nostri elenchi di libri. I corsi prevedono lezioni, esercitazioni, test, appunti o altri supporti didattici. Una singola lezione o video di per sé non è un corso. Un powerpoint non è un corso.

Tutorial interattivi vs. Altro

Se riesci a stamparlo e conservarne l'essenza, non è un tutorial interattivo.

Automazione

  • L'applicazione delle regole di formattazione è automatizzata tramite GitHub Actions usando fpb-lint (guarda .github/workflows/fpb-lint.yml)

  • La validazione dell'URL usa awesome_bot

  • Per attivare la convalida dell'URL, invia un commit che includa un messaggio di commit contenente check_urls=file_to_check:

    check_urls=free-programming-books.md free-programming-books-it.md

  • È possibile specificare più di un file da controllare, utilizzando un singolo spazio per separare ogni voce.

  • Se specifichi più di un file, i risultati della build si basano sul risultato dell'ultimo file controllato. Dovresti essere consapevole che potresti ottenere il passaggio di build verdi a causa di ciò, quindi assicurati di ispezionare il registro di build alla fine della Pull Request facendo clic su "Show all checks" -> "Details".