Contribuire a Moongate

Sono benvenuti contributi come segnalazioni di bug, correzioni, funzionalità, test, documentazione ed esempi. Questa guida spiega come preparare un contributo per la revisione.

Prima di iniziare

Cerca nelle issue esistenti e nelle pull request prima di iniziare. Ogni funzionalità parte da una issue che la descrive in dettaglio, come richiede CODE_CONVENTION.md §13.1; lo stesso vale per una modifica ad API pubbliche, comportamento dei pacchetti o formati di persistenza. Correzioni di bug e documentazione possono andare direttamente in una pull request.

Per una segnalazione di bug, includi versione o commit Moongate, sistema operativo, passaggi di riproduzione, comportamento atteso ed effettivo e log rilevanti. Includi la versione del client per problemi di rete. Rimuovi credenziali e dati personali da qualsiasi cosa condivisa. Le richieste di funzionalità devono spiegare caso d’uso e comportamento previsto, non solo l’implementazione proposta.

Preparare il checkout

Servono Git e l’SDK .NET 10 per compilare la soluzione. La verifica dei package richiede anche Bash e accesso a nuget.org. Per il sito, usa la versione Node in website/.nvmrc; Node non serve per la build C#.

Crea un fork del repository su Codeberg, poi un branch dall’attuale develop:

git clone https://codeberg.org/YOUR-USERNAME/moongate.git
cd moongate
git remote add upstream https://codeberg.org/moongate/moongate.git
git fetch upstream
git switch -c feature/short-description upstream/develop

Usa un nome descrittivo del branch, come fix/packet-length o docs/plugin-guide. Per eseguire un server, vedi la guida Docker, inclusi i file richiesti del client Ultima Online e la configurazione del primo avvio.

Seguire le convenzioni del progetto

Leggi CODE_CONVENTION.md e usa l’ .editorconfig del repository. Definiscono stile C#, namespace, collocazione dei tipi, organizzazione dei test e documentazione delle interfacce pubbliche.

Mantieni le modifiche concentrate su un problema. Segui il codice circostante ed evita formattazioni o refactoring non correlati. Scrivi documentazione, commenti XML pubblici, messaggi di commit e descrizioni delle pull request in inglese. Discuti esplicitamente le modifiche incompatibili e spiega il loro effetto su utenti delle librerie e plugin.

Usa Conventional Commits, per esempio:

fix(network): reject invalid packet lengths
feat(persistence): add a collection query option
docs(plugins): clarify bundle deployment

I messaggi dei commit e le descrizioni delle pull request non portano l’attribuzione di uno strumento di IA: nessun trailer Co-authored-by che nomini uno strumento e nessuna riga “Generated by/with”. Un controllo sulla pull request li rifiuta. Per avere lo stesso rifiuto quando fai il commit, una volta per clone:

git config core.hooksPath .githooks

Verificare le modifiche

Per un controllo rapido mentre lavori, esegui la suite veloce. Non richiede Docker né variabili, perché esclude i test nei namespace Integration, Performance e Stress o con un tratto Category corrispondente:

scripts/test.sh
scripts/test.sh fast --filter 'FullyQualifiedName~Serial'

scripts/test.sh all esegue la suite completa. I test del database e Redis richiedono server PostgreSQL e Redis isolati. Con Docker attivo, i test li avviano autonomamente con Testcontainers: un postgres:17-alpine e un redis:7-alpine (con maxmemory-policy noeviction) per processo di test, rimossi alla fine dell’esecuzione. La prima esecuzione scarica le immagini.

Per usare invece server tuoi, come fa la CI, imposta queste variabili d’ambiente tramite il fornitore di segreti; una variabile impostata prevale sempre sul container:

Variabile	Dipendenza dei test
MOONGATE_TEST_POSTGRES_CONNECTION_STRING	Una connessione Npgsql amministrativa a un server PostgreSQL eliminabile; il ruolo deve poter creare ed eliminare database di test
MOONGATE_TEST_REDIS_CONNECTION_STRING	Una stringa di connessione StackExchange.Redis per un server Redis 7+ eliminabile configurato con maxmemory-policy noeviction

Non puntare queste variabili ai database o all’istanza Redis di uno shard attivo. Senza variabili e senza Docker, i test di integrazione falliscono; non vengono saltati silenziosamente. Esegui i progetti di test in serie con -m:1, come fa la CI, perché i loro host condividono i servizi database.

La CI non esegue la suite di test: eseguila in locale prima di una pull request e prima di una release. I servizi PostgreSQL e Redis dei controlli di release servono solo alla verifica dei pacchetti.

Esegui questi comandi dalla root del repository per replicare i controlli della soluzione in CI:

dotnet restore Moongate.slnx
dotnet format style Moongate.slnx --diagnostics IDE0022 --severity warn --no-restore --verify-no-changes
dotnet build Moongate.slnx -c Release --no-restore
bash scripts/test.sh all -c Release --no-build

scripts/coverage.sh accetta gli stessi argomenti, esegue i test con copertura del codice e scrive un rapporto unificato in artifacts/coverage/index.html. La CI non lo esegue, quindi la pagina Copertura dei test della documentazione pubblicata dice che nessun rapporto era disponibile; esegui lo script in locale per vedere i numeri.

Per i test facoltativi di carico concorrente sul database, vedi Stress test della persistenza PostgreSQL.

Aggiungi o aggiorna test per il comportamento modificato. Per le correzioni di bug, includi un test di regressione che dimostri l’errore. Segui la struttura dei test in CODE_CONVENTION.md e mantieni le asserzioni concentrate sul comportamento osservabile. Le correzioni alla sola prosa non richiedono nuovi test C#.

La CI viene eseguita sulle pull request e sui push a develop e main; modifiche che toccano solo docs/, website/ o file Markdown la saltano. Pull request verso develop e push a develop eseguono solo ripristino, verifica dello stile dei corpi dei metodi e build: esegui i test localmente (bash scripts/test.sh all) prima di aprire la pull request. Pull request verso main, che creano una release, e push a main eseguono i controlli di release: client di amministrazione portabile, package NuGet, esempi README eseguibili e avvisi di terze parti. Nessuno dei due esegue i test: esegui bash scripts/test.sh all -c Release in locale prima di una release. L’immagine Docker di sviluppo (docker.io/tgiachi/moongate:develop) viene ricostruita ogni notte, o su richiesta dalla scheda Actions. Il controllo di amministrazione usa le stesse connessioni di test e richiede Python 3 con supporto venv e accesso per installare le dipendenze in samples/admin-python/requirements.txt:

bash scripts/verify-admin-protos.sh
bash scripts/verify-packages.sh
./scripts/third-party-notices.sh
git diff --exit-code -- THIRD-PARTY-NOTICES.md

Vedi Verifica dei package NuGet per prerequisiti e risoluzione dei problemi. Se una modifica alle dipendenze aggiorna gli avvisi, revisiona e includi l’aggiornamento nel commit affinché il confronto CI sia pulito.

Per modifiche alla documentazione o al sito, esegui:

npm --prefix website ci
npm --prefix website test
npm --prefix website run build

La build verifica link locali, immagini e frammenti delle intestazioni. Modifica i sorgenti Markdown originali invece dei file generati del sito. Vedi Scrivere documentazione per comandi di anteprima e registrazione delle pagine. Gli esempi README delle librerie conservano i marcatori nuget-smoke affinché la verifica dei package possa compilarli ed eseguirli.

Inviare una pull request

1. Esegui il commit della modifica mirata e il push del branch sul tuo fork.
2. Apri una pull request verso moongate/moongate:develop.
3. Spiega problema, comportamento risultante, issue rilevante e controlli eseguiti. Evidenzia modifiche di compatibilità ed eventuali controlli non eseguibili.
4. Rispondi alla revisione e risolvi gli errori CI prima del merge. Aggiorna la documentazione quando cambiano comportamento o configurazione.

Mantieni le discussioni rispettose e concentrate sulla modifica. I manutentori revisionano e integrano i contributi; aprire una pull request non richiede la pubblicazione di package o la creazione di una release.

I maintainer creano le release con releaser-pleaser. A ogni push su main mantiene aperta una pull request con la versione successiva, calcolata dai messaggi Conventional Commit, il changelog e la versione in Directory.Build.props e nel chart Helm. Il merge di quella pull request crea il tag e la release, e il tag pubblica gli archivi, l’immagine Docker, il chart Helm, i pacchetti NuGet e il sito. Fino alla 1.0 scrivi una breaking change come feat: e descrivila nella pull request: un ! proporrebbe la 1.0.0.

La licenza del progetto è disponibile in LICENSE. Mantieni intatti gli avvisi esistenti di copyright e licenza; l’attribuzione delle dipendenze è registrata in THIRD-PARTY-NOTICES.md.