Manual del contribuidor

OSIRIS JSON es desenvolupa en públic i rep amb entusiasme contribucions de qualsevol mida: preguntes, aclariments, exemples, revisions i millores de tooling. Com a projecte open source, creiem a retornar valor als nostres contribuïdors i ens agrada ajudar amb orientació sobre PRs, redacció tècnica i com convertir qualsevol idea de funcionalitat en realitat.

[!Tip]

Per a nous contribuïdors: Dona un cop d’ull a https://github.com/firstcontributions/first-contributions per obtenir informació útil sobre com contribuir

[!Info] Etapa MVP (maintainer en solitari) OSIRIS JSON està mantingut actualment per un únic maintainer principal. Les revisions i respostes s’ofereixen segons disponibilitat i poden trigar depenent de la càrrega de treball. L’enfocament és mantenir l’especificació coherent, vendor-neutral i estable mentre es construeix l’ecosistema inicial.

On participar

En què pots contribuir

Documentació (punt de partida recomanat)

Les millores a la documentació sempre són valuoses i normalment les més ràpides de revisar:

• corregir errades i enllaços trencats
• aclarir la redacció on la spec sigui ambigua
• millorar les explicacions i la navegació entre pàgines
• ampliar la guia sobre “how to validate” o “how to read an OSIRIS JSON document”

Exemples

Pots contribuir:

• proposant nous escenaris d’exemple
• millorant la llegibilitat i la consistència dels exemples existents
• afegint comentaris o notes de suport que ajudin els lectors a entendre per què certs camps hi són presents

Especificació i schema

Per a contribucions relacionades amb spec/schema:

• obre una issue descrivint el canvi i la seva motivació
• inclou un exemple mínim que demostri el problema
• proposa el canvi més petit possible que preservi la compatibilitat

Com fer que les contribucions siguin fàcils de revisar

• Prefereix PRs petits i enfocats.
• Evita barrejar canvis no relacionats (per exemple, refactor + funcionalitat nova al mateix PR).
• Mantén un llenguatge precís (les afirmacions normatives han d’utilitzar MUST/SHOULD/MAY només quan correspongui).
• Si un canvi pot afectar la compatibilitat, indica-ho explícitament a la descripció del PR.

Contribuïdors

Aquest projecte està mantingut actualment per un únic maintainer principal. Els contribuïdors s’aniran llistant aquí i a la pàgina del maintainer amb el temps.

Code of Conduct

La participació a la comunitat OSIRIS JSON està regida pel Code of Conduct.
Llegeix el Code of Conduct

Contribucions assistides per IA (permeses, però amb responsabilitat)

Fer servir IA com a suport està bé. El que no està bé és produir issues/PRs en massa sense entendre el projecte.

Si fas servir IA:

• Ets responsable de la correcció i de l’abast
• Llegeix i entén el codi/la spec que estàs canviant
• Valida els resultats (tests, linters, validació de schema, exemples)
• No obris issues “especulatives” que no hagis reproduït
• Evita refactors improvisats que reanomenin/reformatin grans àrees sense propòsit

Els maintainers poden tancar sense una discussió extensa:

• Issues duplicades
• Issues sense passos/context reproduïbles
• PRs clarament de baix esforç, generats automàticament o no alineats amb la direcció del projecte

Primers passos

1. Fes un fork del repo i clona el teu fork
2. Crea una branca al teu fork:
   • feat/<short-topic> or fix/<short-topic>
3. Fes els teus canvis en commits petits
4. Obre aviat un Draft PR si vols retroalimentació
5. Marca’l com a llest quan:
   • Tests pass
   • Docs/examples updated
   • La descripció del PR estigui completa

Llista de verificació de Pull Request

Inclou a la descripció del teu PR:

• What canvia aquest PR?
• Why és necessari? (enllaç a issue/discussion)
• How el vas provar?
• Hi ha breaking changes?

Checklist

• Vaig enllaçar la issue/discussion rellevant (o vaig explicar per què no existeix)
• Vaig mantenir l’abast enfocat i vaig evitar canvis no relacionats
• Vaig afegir/actualitzar tests (si aplica)
• Vaig actualitzar docs/examples (si aplica)
• Vaig executar formatting/linking/tools utilitzats per aquest repo (si aplica)

Missatges de commit (recomanat)

Fes servir missatges clars, opcionalment Conventional Commits:

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

Llicència

En contribuir, acceptes que les teves contribucions queden llicenciades sota la llicència del projecte.

GSoC (o programes similars)

Si contribueixes pensant en una candidatura:

• Enfoca’t en una àrea significativa
• Demostra que pots comunicar-te amb claredat, entregar petites millores i iterar a partir de la retroalimentació
• Un breu design doc o una discussió de proposta val més que molts PRs de baix impacte