Contribuire

Fai una piccola modifica nel punto giusto e inviala come pull request.

Prima di iniziare

• Apri prima un’issue, oppure commentane una esistente. Spiega cosa vuoi cambiare e perché.
• Aspetta una risposta, così non costruisci qualcosa che non verrà accettato.
• Completa la Configurazione per poter compilare ed eseguire HolyArrs.

Le domande vanno su Discord. Le idee vanno su r/HolyArrs. Le issue servono per i bug e la roadmap.

Invia la tua prima pull request

1. Trova il modulo a cui appartiene la tua modifica. I nomi in Moduli corrispondono ai nomi delle cartelle, quindi un avviso Discord sbagliato è una modifica in alerts.

2. Fai la modifica in app/backend/internal/<module>/ e app/frontend/src/lib/<module>/. Limitati a una correzione o a una funzione.

3. Compila l’app web, poi il programma, e prova la modifica nel browser. Vedi Configurazione.

4. Esegui i controlli in Test.

   Non dovresti vedere nessun errore.

5. Se hai cambiato una pagina, esegui il suo progetto end-to-end, per esempio npm --prefix app/frontend run e2e -- --project=movies.

6. Apri la pull request. Collega l’issue, spiega cosa è cambiato e come l’hai provato, e aggiungi o aggiorna i test per la modifica.

7. Alla tua prima pull request, un bot ti chiede di firmare l’accordo di licenza del contributore. Rispondi con l’unica frase che ti chiede.

Nota

Il copyright del tuo lavoro resta tuo. L’accordo permette di offrire HolyArrs sotto la AGPL-3.0 e sotto una licenza commerciale. Tutto ciò che viene integrato resta disponibile anche sotto la AGPL-3.0. Il testo è in .github/CLA.md.

Scelte

Dove va una modifica

Modifica	Vai a
Una nuova route	Moduli
Un nuovo modulo	Moduli. Apri prima un’issue
Una funzione in sospeso	Configurazione
Una versione	Pubblicare una versione. Solo per chi mantiene il progetto

Com’è fatta una buona pull request

• Scrivi commenti che spiegano perché il codice fa quello che fa. Nei commenti niente numeri della roadmap, date, nomi o lineette em.
• Lascia stare i testi dell’app, a meno che l’issue non riguardi proprio i testi.
• Lascia invariati i percorsi API già pubblicati, i nomi dei campi, le chiavi delle impostazioni, i nomi delle tabelle e i nomi dei processi. Aggiungi, non rinominare mai.

Se non funziona

Sintomo. Un controllo sulla struttura fallisce. Causa. Il messaggio indica il file e la regola. Soluzione. Sposta il codice, oppure passa dati semplici dal modulo superiore. Vedi Moduli.

Sintomo. L’app web sembra vecchia. Causa. Il programma serve la build che ha incorporato. Soluzione. Compila di nuovo l’app web prima del programma.

Sintomo. I test end-to-end non partono. Causa. Il browser di test non è installato. Soluzione. Esegui npx --prefix app/frontend playwright install chromium.

Per esperti

Regole che una pull request deve rispettare

• Un modulo parla con un altro modulo solo tramite il suo servizio (Go) o il suo index.ts (web). Mai tramite il suo store o i suoi file.
• L’SQL vive solo nei file store*.go di un modulo, sulle tabelle di quel modulo.
• Una parte web va in lib/ui solo quando la usano 2 o più moduli.
• Niente pacchetti util, common, shared o helpers.
• Ogni chiamata verso l’esterno passa da core/outbound.

I test controllano queste regole, quindi un import sbagliato fa fallire la compilazione. L’elenco completo e i nomi dei controlli sono in Moduli.

Cosa esegue CI

Processo	Esegue
Web	check, lint, test, build e la suite end-to-end
Go	go build, go vet e go test -timeout 60m ./... su amd64 e arm64, in modo nativo e in emulazione
Race	go test -race ./...
Contratto	La corrispondenza con openapi.json, i controlli degli ambiti su ogni route, la suite dei downloader
Guasti e scala	Prove su crash, scritture lente, servizi esterni difettosi e memoria
Immagine	Un’immagine di sviluppo viene compilata, avviata e dichiara la sua versione

I dettagli delle prove lunghe sono in Test.

Correlati

• Configurazione
• Test
• Architettura