Manuale del contributore

OSIRIS JSON è sviluppato in pubblico e accoglie con entusiasmo contributi di qualsiasi dimensione: domande, chiarimenti, esempi, revisioni e miglioramenti del tooling. Come progetto open source, crediamo nel restituire valore ai nostri contributori e siamo felici di aiutare con indicazioni sui PR, sulla scrittura tecnica e nel trasformare qualsiasi idea di funzionalità in realtà.

[!Tip]

Per i nuovi contributori: Dai un’occhiata a https://github.com/firstcontributions/first-contributions per informazioni utili su come contribuire

[!Info] Fase MVP (solo maintainer) OSIRIS JSON è attualmente mantenuto da un unico lead maintainer. Revisioni e risposte sono fornite in base al miglior sforzo possibile e possono richiedere tempo a seconda del carico di lavoro. L’obiettivo è mantenere la specifica coerente, vendor-neutral e stabile mentre si costruisce l’ecosistema iniziale.

Dove partecipare

Cosa puoi contribuire

Documentazione (punto di partenza consigliato)

I miglioramenti alla documentazione sono sempre preziosi e di solito i più rapidi da revisionare:

• correggere refusi e link non funzionanti
• chiarire la formulazione dove la spec è ambigua
• migliorare spiegazioni e navigazione tra le pagine
• ampliare le indicazioni su “come validare” o “come leggere un documento OSIRIS JSON”

Esempi

Puoi contribuire:

• proponendo nuovi scenari di esempio
• migliorando leggibilità e coerenza degli esempi esistenti
• aggiungendo commenti o note di accompagnamento che aiutino i lettori a capire perché alcuni campi sono presenti

Specifica e schema

Per contributi relativi a spec/schema:

• apri una issue che descriva il cambiamento e la motivazione
• includi un esempio minimo che dimostri il problema
• proponi il cambiamento più piccolo possibile che preservi la compatibilità

Come mantenere i contributi facili da revisionare

• Preferisci PR piccoli e focalizzati.
• Evita di mescolare cambiamenti non correlati (ad esempio refactor + nuova funzionalità nello stesso PR).
• Mantieni il linguaggio preciso (le affermazioni normative dovrebbero usare MUST/SHOULD/MAY solo dove appropriato).
• Se un cambiamento potrebbe influire sulla compatibilità, evidenzialo esplicitamente nella descrizione del PR.

Contributori

Questo progetto è attualmente mantenuto da un unico lead maintainer. I contributori verranno elencati qui e nella pagina del maintainer nel tempo.

Code of Conduct

La partecipazione alla community OSIRIS JSON è regolata dal Code of Conduct.
Leggi il Code of Conduct

Contributi assistiti da IA (consentiti, ma con responsabilità)

Usare l’IA come supporto va bene. Quello che non va bene è produrre in massa issues/PRs senza comprendere il progetto.

Se usi l’IA:

• Sei responsabile della correttezza e dell’ambito
• Leggi e comprendi il codice/la spec che stai modificando
• Valida gli output (tests, linters, validazione dello schema, esempi)
• Non aprire issues “speculative” che non hai riprodotto
• Evita refactor frettolosi che rinominano/riformattano grandi aree senza uno scopo

I maintainer possono chiudere senza discussione estesa:

• Issue duplicate
• Issue prive di passaggi/contesto riproducibili
• PR chiaramente di scarso impegno, auto-generati o non allineati con la direzione del progetto

Per iniziare

1. Fai un fork del repo e clona il tuo fork
2. Crea un branch nel tuo fork:
   • feat/<short-topic> or fix/<short-topic>
3. Apporta le modifiche in piccoli commit
4. Apri presto un Draft PR se vuoi feedback
5. Segna come pronto quando:
   • Tests pass
   • Docs/examples updated
   • La descrizione del PR è completa

Checklist Pull Request

Includi nella descrizione del PR:

• What cambia questo PR?
• Why è necessario? (link a issue/discussion)
• How lo hai testato?
• Ci sono breaking changes?

Checklist

• Ho collegato la issue/discussion rilevante (o spiegato perché non esiste)
• Ho mantenuto l’ambito focalizzato ed evitato modifiche non correlate
• Ho aggiunto/aggiornato tests (se applicabile)
• Ho aggiornato docs/examples (se applicabile)
• Ho eseguito formatting/linking/tools usati da questo repo (se applicabile)

Messaggi di commit (consigliato)

Usa messaggi chiari, opzionalmente Conventional Commits:

• feat: ...
• fix: ...
• docs: ...
• chore: ...

Licenza

Contribuendo, accetti che i tuoi contributi siano concessi in licenza secondo la licenza del progetto.

GSoC (o programmi simili)

Se stai contribuendo pensando a una candidatura:

• Concentrati su un’area significativa
• Mostra di saper comunicare chiaramente, consegnare piccoli miglioramenti e iterare sul feedback
• Un breve design doc o una discussione su una proposta vale più di molti PR a basso impatto