Manual del contribuidor

OSIRIS JSON se desarrolla en público y recibe con entusiasmo contribuciones de cualquier tamaño: preguntas, aclaraciones, ejemplos, revisiones y mejoras de tooling. Como proyecto open source, creemos en devolver valor a nuestros contribuidores y nos da gusto ayudar con orientación sobre PRs, redacción técnica y cómo convertir cualquier idea de funcionalidad en una realidad.

[!Tip]

Para nuevos contribuidores: Échale un vistazo a https://github.com/firstcontributions/first-contributions para obtener información útil sobre cómo contribuir

[!Info] Etapa MVP (maintainer en solitario) OSIRIS JSON está mantenido actualmente por un único maintainer principal. Las revisiones y respuestas se ofrecen según disponibilidad y pueden tardar dependiendo de la carga de trabajo. El enfoque es mantener la especificación coherente, vendor-neutral y estable mientras se construye el ecosistema inicial.

Dónde participar

En qué puedes contribuir

Documentación (punto de partida recomendado)

Las mejoras en la documentación siempre son valiosas y por lo general son las más rápidas de revisar:

• corregir erratas y enlaces rotos
• aclarar la redacción donde la spec sea ambigua
• mejorar las explicaciones y la navegación entre páginas
• ampliar la guía sobre “how to validate” o “how to read an OSIRIS JSON document”

Ejemplos

Puedes contribuir:

• proponiendo nuevos escenarios de ejemplo
• mejorando la legibilidad y la consistencia de los ejemplos existentes
• agregando comentarios o notas de apoyo que ayuden a los lectores a entender por qué ciertos campos están presentes

Especificación y schema

Para contribuciones relacionadas con spec/schema:

• abre una issue describiendo el cambio y su motivación
• incluye un ejemplo mínimo que demuestre el problema
• propone el cambio más pequeño posible que preserve la compatibilidad

Cómo hacer que las contribuciones sean fáciles de revisar

• Prefiere PRs pequeños y enfocados.
• Evita mezclar cambios no relacionados (por ejemplo, refactor + nueva funcionalidad en el mismo PR).
• Mantén un lenguaje preciso (las afirmaciones normativas deben usar MUST/SHOULD/MAY solo cuando corresponda).
• Si un cambio puede afectar la compatibilidad, indícalo explícitamente en la descripción del PR.

Contribuidores

Este proyecto está mantenido actualmente por un único maintainer principal. Los contribuidores se irán listando aquí y en la página del maintainer con el tiempo.

Code of Conduct

La participación en la comunidad OSIRIS JSON está regida por el Code of Conduct.
Lee el Code of Conduct

Contribuciones asistidas por IA (permitidas, pero con responsabilidad)

Usar IA como apoyo está bien. Lo que no está bien es producir issues/PRs en masa sin entender el proyecto.

Si usas IA:

• Eres responsable de la corrección y del alcance
• Lee y entiende el código/la spec que estás cambiando
• Valida los resultados (tests, linters, validación del schema, ejemplos)
• No abras issues “especulativas” que no hayas reproducido
• Evita refactors improvisados que renombren/reformateen grandes áreas sin propósito

Los maintainers pueden cerrar sin una discusión extensa:

• Issues duplicadas
• Issues sin pasos/contexto reproducibles
• PRs claramente de bajo esfuerzo, generados automáticamente o no alineados con la dirección del proyecto

Primeros pasos

1. Haz un fork del repo y clona tu fork
2. Crea una rama en tu fork:
   • feat/<short-topic> or fix/<short-topic>
3. Haz tus cambios en commits pequeños
4. Abre pronto un Draft PR si quieres retroalimentación
5. Márcalo como listo cuando:
   • Tests pass
   • Docs/examples updated
   • La descripción del PR esté completa

Lista de verificación de Pull Request

Incluye en la descripción de tu PR:

• What cambia este PR?
• Why es necesario? (enlace a issue/discussion)
• How lo probaste?
• ¿Hay breaking changes?

Checklist

• Enlacé la issue/discussion relevante (o expliqué por qué no existe)
• Mantuve el alcance enfocado y evité cambios no relacionados
• Añadí/actualicé tests (si aplica)
• Actualicé docs/examples (si aplica)
• Ejecuté formatting/linking/tools usados por este repo (si aplica)

Mensajes de commit (recomendado)

Usa mensajes claros, opcionalmente Conventional Commits:

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

Licencia

Al contribuir, aceptas que tus contribuciones se licencian bajo la licencia del proyecto.

GSoC (o programas similares)

Si contribuyes pensando en una candidatura:

• Enfócate en un área significativa
• Demuestra que puedes comunicarte con claridad, entregar pequeñas mejoras e iterar a partir de la retroalimentación
• Un breve design doc o una discusión de propuesta vale más que muchos PRs de bajo impacto