Merge branch 'main' into add/leadership

.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

.github/FUNDING.yml

@@ -0,0 +1 @@
+open_collective: il-libro-open-source

.github/workflows/deploy.yml

@@ -0,0 +1,62 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+# Sample workflow for building and deploying a Jekyll site to GitHub Pages
+name: Deploy Jekyll site to Pages
+
+on:
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.2"
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+          cache-version: 0 # Increment this number if you need to re-download cached gems
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v3
+      - name: Build with Jekyll
+        # Outputs to the './_site' directory by default
+        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
+        env:
+          JEKYLL_ENV: production
+      - name: Upload artifact
+        # Automatically uploads an artifact from the './_site' directory by default
+        uses: actions/upload-pages-artifact@v2
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.github/workflows/formatting-validation.yml

@@ -8,9 +8,9 @@ jobs:
   format:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
           node-version: 18
       - name: Prettier Check
-        run: npm run format:check
+        run: npm run format:check

.gitignore

@@ -24,3 +24,6 @@ dist/
 .env
 .env.*
 !.env.example
+
+# Site
+_site

.prettierrc

@@ -1,4 +1,5 @@
 {
   "singleAttributePerLine": true,
-  "trailingComma": "es5"
+  "trailingComma": "es5",
+  "endOfLine": "lf"
 }

AMBASSADORS.md

@@ -1,15 +1,21 @@
 # Cos'è un Ambassador?
 
-1. Un ambassador è una qualsiasi persona che voglia rendersi utile fornendo il proprio contributo al progetto, tanto da impegnarsi _ufficiosamente_ nella sua riuscita. La nomina non è un vincolo, ma un _buon proposito_ che vorremmo venisse rispettato nei confronti della community che contribuisce alla nomina.
-2. Un ambassador si occuperà di uno o più capitoli del libro, in base alla quantità di persone che si proporranno, e sarà la voce ultima nella presa di decisione a riguardo, sempre rispettando il concetto comunitario che segue il progetto.
-3. Un capitolo può essere _soprasseduto_ da più di un ambassador qualora sia ritenuto di rilevanza per più di una persona. Le decisioni in quel caso dovranno essere unanimi. Per una corretta gestione dei conflitti, qualora ci sia una differenza di opinione insanabile su un tema o su una modifica, sarò io stesso l'ago della bilancia rendendo dispari la quantità degli ambassador responsabili del capitolo in questione solo per quella specifica situazione.
-4. Un ambassador rimarrà tale a meno di particolari situazioni come offese, insulti, comportamento immorale o scorretto nei confronti della community.
-5. Un ambassador avrà totale operatività sul repository, avendo il ruolo di _Maintain_ di GitHub, o _Write_ qualora lo si riterrà sufficiente.
-6. Un ambassador non ha alcun vincolo di responsabilità nei confronti del progetto qualora decidesse di abbandonarlo, ma chiediamo alla persona il tempo necessario ad essere sostituita prima di abbandonare il proprio _presidio_.
-7. Qualora gli ambassador reputeranno la mia gestione del progetto non all'altezza o non in linea con la filosofia del progetto, potranno aprire un sondaggio che - superato il 50% di voti positivi in un tempo che loro stabiliranno - mi imporrà di indicare un nuovo maintainer che loro stessi decideranno in autonomia.
+Importante partire dal "Perché" e dal risultato: avere il Libro Open Source.
+Nessuna delle decisioni che prendiamo ha alcun senso se il libro non viene scritto ed il progetto non va avanti.
+
+Sulla base di questo un Ambassador è:
+
+1. Una persona che ha l'ownership di un capitolo o area del libro -> Può scrivere in prima persona oppure assicurarsi che altri contributor riempiano i contenuti, ma in ultima istanza è la persona responsabile che quell'area non resti vuota.
+2. Una persona che fa parte di un working group - in questo caso il contributo che porta al progetto non riguarda i contenuti ma altri compiti comunque importanti a livello gestionale.
+3. Una persona che svolge entrambe le funzioni di cui ai punti 1 e 2.
+
+Va ribadito che il fatto di "seguire le linee guida" è conditio sine qua non, si applica quindi a tutti i casi 1 2 e 3, senza bisogno di essere nelle definizioni stesse.
+
+NOTA: Il title "Ambassador" è in fase di valutazione; dal momento che stiamo valutando diversi tipi di contribuzione, può darsi che il termine "Ambassador" possa essere tramutato in "Maintainer", ed affiancato ai ruoli di Ambassador propriamente detti, "Friends" e "Contributors".
+Il team Governance si preoccuperà di dare aggiornamenti a riguardo.
 
 # Come si diventa Ambassador?
 
 1. È presente una [discussione ad hoc](https://github.com/Il-Libro-Open-Source/book/discussions/5) che resterà sempre aperta permettendo a chiunque di candidarsi per un posto tra gli Ambassadors.
-2. Ogni _X_ settimane, numero che stabiliremo assieme in seguito, i candidati di quel periodo e quelli precedentemente non eletti verranno votati in apposite survey per riempire i posti aperti in quello specifico momento. I candidati verranno nominati Ambassador a partire dal candidato con il maggior numero di punti fino ad esaurimento posti disponibili alla fine degli _Y_ giorni stabiliti assieme per considerare chiuso il processo di nomina.
+2. A periodi non ancora definiti, i candidati verranno votati in apposite survey per riempire i posti aperti in quello specifico momento. I candidati verranno nominati Ambassador a partire dal candidato con il maggior numero di punti fino ad esaurimento posti disponibili alla fine dei giorni stabiliti assieme per considerare chiuso il processo di nomina.
 3. Una volta nominato, un ambassador diventerà effettivo nel tempo pratico necessario agli owner del progetto di nominarlo, quindi da una manciata di ore a qualche giorno in base alla disponibilità.

CONTRIBUTING.md

@@ -1,40 +1,95 @@
 # Come contribuire al repository
 
-## Prima installazione
+## Benvenuto!
 
-Dopo aver clonato il progetto:
+Grazie per aver deciso di contribuire al progetto!  
+In questa pagina troverai tutte le informazioni necessarie per poter contribuire al progetto in varie forme.
 
-```bash
-npm i
-```
+## In che modo posso contribuire?
+
+Per contribuire nella stesura del libro puoi fare una qualsiasi delle seguenti attività.
+
+### Proporre un nuovo capitolo
+
+Se hai un'idea per un capitolo, puoi proporla aprendo una nuova issue.  
+Github ti proporrà un template per la creazione della issue, che ti suggeriamo di utilizzare.  
+Inserisci quante più informazioni possibili e specifica se vorresti occuparti interamente della prima stesura o se invece vorresti produrre il contenuto in collaborazione con altri contributori.
+
+Una volta aperta la issue, verrà automaticamente assegnata una label `nuovo-capitolo`.  
+A questo punto, un qualsiasi Ambassador potrebbe decidere di _assegnare_ a se stesso la issue. Ti consigliamo di pubblicizzare la tua idea in ogni modalità a te possibile e/o contattare eventuali Ambassador di tua conoscenza per chiedere loro di dare un'occhiata alla tua proposta e valutare la possibilità di _assegnare_ la issue a se stessi.
+
+Nel momento in cui un Ambassador deciderà di _assegnare_ la issue a se stesso, un branch verrà creato in maniera automatica e il lavoro di stesura potrà cominciare.
+
+Prosegui nella lettura di questa pagina alla voce [Modalità di stesura di un capitolo](#modalità-di-stesura-di-un-capitolo) per capire come procedere da qui.
+
+### Proporre una modifica ad un capitolo esistente
+
+Se hai un'idea per migliorare un capitolo esistente, puoi proporla aprendo una nuova issue.
+Github ti proporrà un template per la creazione della issue, che ti suggeriamo di utilizzare.  
+In alternativa, potresti aprire direttamente una Pull Request, ma ti consigliamo di aprire una issue per discutere prima della modifica da apportare e capire se la tua idea è condivisa dalla community.
+
+### Modalità di stesura di un capitolo
+
+Bene, hai individuato un capitolo a cui contribuire / da modificare e vuoi cominciare a scrivere dei contenuti. Ma come?
+
+Le modalità di stesura del capitolo sono principalmente due:
+
+- In accordo con la persona del team Ambassador assegnataria del capitolo di interesse, potrete decidere di mettervi in contatto per lavorare insieme alla stesura del capitolo. In questo caso, potrete decidere di utilizzare un qualsiasi strumento di scrittura collaborativa (Google Docs, Office 365, ecc.) e di caricare il contenuto nel branch una volta terminato. Per comodità, si suggerisce di lasciare alla figura di Ambassador il compito di caricare il contenuto nel repository rimuovendo la necessità di una ulteriore Pull Request.
 
-per installare le librerie
+- In accordo con la persona del team Ambassador assegnataria del capitolo, potrai stendere in prima battuta il contenuto del capitolo e far sì che la persona assegnataria ti faccia da revisore e guida. In questo caso, sarà necessario fare un fork del branch relativo al capitolo e aprire una Pull Request che dovrà puntare a quello stesso branch come destinazione.
+  Una volta aperta la Pull Request, la persona assegnataria del capitolo potrà iniziare a revisionare il contenuto e a suggerire modifiche.  
+  Una volta terminato il lavoro, la persona assegnataria del capitolo aprirà una Pull Request (o modificherà quella già presente da `draft` a `ready for review`) e chiederà una revisione al resto della community. Le regole di approvazione dei contenuti sono regolate dal Governance Group del progetto e sono disponibili [qui](https://github.com/Il-Libro-Open-Source/book/blob/main/GUIDELINES-CONTENUTI.md).
 
-## Formattazione
+## Scrivere i contenuti
+
+I contenuti del libro sono scritti in formato markdown e sono organizzati in cartelle e file.  
+Sarà sufficiente avere una qualsiasi versione di Node.js installata sul proprio computer per poter formattare i file markdown in maniera automatica e un qualsiasi IDE per la stesura.
+
+### Prima installazione
+
+Dopo aver clonato il progetto ed essendosi spostati sul branch relativo al capitolo di interesse, eseguire il comando `npm i` per installare le librerie.
+
+### Formattazione
 
 Tutti i file markdown devono essere formattati con [Prettier](https://prettier.io/) per una miglior leggibilità e per evitare inutili merge conflict se più persone lavorano allo stesso file.
 
-Per formattare da linea di comando tutti i file è necessario avere [Node](https://nodejs.org/it) installato sul proprio computer e lanciare il seguente comando nella cartella del repository:
+Per formattare da linea di comando tutti i file è sufficiente lanciare il seguente comando nella cartella del repository:
 
 ```bash
-npm run format:write -- *.md
+npm run format:write
 ```
 
 Fortunatamente i principali IDE supportano Prettier tramite delle estensioni, di seguito alcuni esempi:
 
-### Visual Studio Code
+#### Visual Studio Code
 
 Per formattare i file markdown con Visual Studio Code è necessario installare l'estensione [Prettier - Code formatter](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode).
 
 Un buon consiglio è tenere attivo il flag `Format On Save` direttamente nelle impostazioni di vscode per evitare di dover formattare ogni volta a mano.
 
-## Conventional commits
+#### JetBrains IDE (WebStorm, IntelliJ, ecc.)
+
+Per formattare i file markdown con IDE JetBrains è necessario installare l'estensione [Prettier](https://plugins.jetbrains.com/plugin/10456-prettier), tranne per WebStorm che include già Prettier di default.
+
+Alcuni suggerimenti di configurazione si possono trovare [qui](https://prettier.io/docs/en/webstorm).
+
+#### Vim
+
+Per formattare i file markdown con Vim è necessario installare il plugin [vim-prettier](https://github.com/prettier/vim-prettier).
+
+Alcuni suggerimenti di configurazione si possono trovare [qui](https://prettier.io/docs/en/vim).
+
+#### Altri IDE
+
+Nella documentazione di Prettier sono presenti le istruzioni per configurare il tool nel proprio IDE preferito: [Editor Integration](https://prettier.io/docs/en/editors).
+
+### Conventional commits
 
 Per mantenere uno storico e poter costruire dei changelog è richiesto a tutti i contributori del progetto di utilizzare i [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).  
 In pratica è necessario utilizzare dei prefissi per i commit che indicano il tipo di commit e il contesto, ad esempio:
 
 ```bash
-git commit -m "feat: Aggiunta nuova pagina"
+git commit -m "feat: aggiunta nuova pagina"
 ```
 
 ## Lingua e contenuti
@@ -43,6 +98,11 @@ Il libro è, in questo momento, orientato ad un pubblico italiano.
 Volendo essere accessibile alla platea più ampia possibile, è necessario utilizzare un linguaggio semplice e chiaro, espresso in lingua italiana, per i contenuti, le cartelle, i commit, le Pull Requests, i commenti, ecc.  
 Seppur abituati a scrivere in inglese commit e Pull Requests, richiediamo a chi contribuisce di utilizzare la lingua italiana anche in questi casi, _al netto del `<type>` dei commit_ per seguire i [Conventional Commits](#conventional-commits), che resteranno in inglese.
 
+Per quanto riguarda i capitoli del libro, è stata già predisposta una futura integrazione di ulteriori lingue (traduzioni) utilizzando un approccio `language driven` per la struttura delle cartelle. Si avrà quindi, ad esempio: `docs/it/nome-del-capitolo.md` per la lingua italiana, `docs/en/name-of-the-chapter.md` per l'inglese, e così via.
+
+> [!NOTE]  
+> Il nome del file (`nome-del-capitolo.md`) rappresenta, a tutti gli effetti, lo `slug` dell' url. Cercando sempre di mantenere una nomenclatura efficace e concisa (esempio: ✅ `sviluppo-mobile` e non ❌ `capitolo-sulle-metodologie-di-sviluppo-per-applicazioni-mobile`), è necessario utilizzare la convenzione di nomenclatura `Kebab case` (quindi parole in minuscolo separate da un `-`).
+
 ## Linee Guida
 
 Prima di stendere contenuti o proporre delle Pull Request si suggerisce di dare una lettura alle [Linee Guida](https://github.com/Il-Libro-Open-Source/book/blob/main/GUIDELINES.md) (E relativo [Cheatsheet](https://github.com/Il-Libro-Open-Source/book/blob/main/GUIDELINES-CHEATSHEET.md)) da rispettare quando si interagisce con il repository.

GUIDELINES-CONTENUTI.md

@@ -0,0 +1,37 @@
+# Linee guida per l'approvazione e la disapprovazione dei contenuti
+
+Attualmente sono presenti quattro modalità di contribuzione:
+
+- Un membro del team Ambassador può aprire una PR da un _branch_ verso il branch _main_.
+- Un contributor esterno - o Ambassador - può aprire una PR da un proprio _fork_ verso il branch _main_.
+- Un contributor esterno - o Ambassador - può aprire una PR da un proprio _fork_ verso un _branch_ di un Ambassador.
+
+Queste quattro modalità seguiranno dei processi di approvazione contenuti che verranno descritti in questo documento.
+
+## Approvazione di un contenuto verso un branch
+
+Per l'approvazione di un contenuto all'interno di un branch, che sia da parte di un Ambassador che di una figura esterna, sarà sufficiente:
+
+- Approvazione di almeno il 50%+1 degli Ambassador assegnatari. In caso di non raggiungimento del quorum entro 15 giorni dall'apertura della PR, un qualsiasi altro Ambassador potrà fare le veci degli assegnatari non votanti.
+- Superato il tempo massimo di 15 giorni dall'apertura della PR - O 15 giorni dall'ultimo commento o approvazione da parte di un Ambassador -, qualora non venga raggiunto il quorum questa sarà considerata non valida e verrà chiusa da qualsiasi Ambassador avesse modo di farlo e verrà richiesto alla persona che ha aperto la PR di riproporla cercando di creare più coinvolgimento o di modificarne il wording.
+
+Non si ritiene necessaria la presenza del Drafting Group in questa fase in quanto sarà comunque necessario un successivo passaggio prima dell'inserimento in _main_ dei contenuti nel quale loro saranno coinvolti e questo step creerebbe solo eccessivo lavoro per il gruppo.
+
+Si precisa che il conteggio dei tempi di approvazione e raggiungimento del quorum inizia quando la Pull Request (PR) è contrassegnata come _ready for review_, e non più in _draft_.
+
+## Approvazione di un contenuto verso _main_
+
+Per l'approvazione di un contenuto all'interno di main, che sia da parte di un Ambassador che di una figura esterna, sarà sufficiente:
+
+- Approvazione di almeno 5 Ambassador.
+- Approvazione di almeno 1 membro del Drafting Group.
+- Superato il tempo massimo di 15 giorni dall'apertura della PR - O 15 giorni dall'ultimo commento o approvazione da parte di un Ambassador -, questa sarà considerata non valida e verrà chiusa da qualsiasi Ambassador avesse modo di farlo e verrà richiesto alla persona che ha aperto la PR di riproporla cercando di creare più coinvolgimento o di modificarne il wording.
+
+## Disapprovazione di un contenuto
+
+Per esprimere la disapprovazione dei contenuti sarà sufficiente che un membro del team Ambassador commenti la PR indicando in maniera chiara il proprio dissenso (Pollice giù 👎, commento chiaro es. "Non approvo questo contenuto"), al quale deve seguire una spiegazione chiara. Il semplice dissenso non motivato non verrà considerato come valido.
+
+La disapprovazione andrà a ridurre di 1 i numeri per il raggiungimento dei criteri di cui sopra.
+
+Di conseguenza, a titolo di esempio, una PR verso main con 5 voti a favore e approvazione del drafting group ma con una disapprovazione renderà necessaria un'ulteriore approvazione per poter passare.
+Lo stesso vale per il conteggio del Drafting Group, per cui la disapprovazione da parte di uno dei suoi membri richiederà l'approvazione di altri 2 di essi per raggiungere il netto positivo di 1.

Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gem "just-the-docs"