Manual do contribuidor

O OSIRIS JSON é desenvolvido em público e recebe com entusiasmo contribuições de qualquer tamanho: perguntas, esclarecimentos, exemplos, revisões e melhorias de tooling. Como projeto open source, acreditamos em retribuir aos nossos contribuidores e temos satisfação em ajudar com orientações sobre PRs, redação técnica e em transformar qualquer ideia de funcionalidade em realidade.

[!Tip]

Para novos contribuidores: Dê uma olhada em https://github.com/firstcontributions/first-contributions para obter informações úteis sobre como contribuir

[!Info] Estágio de MVP (maintainer solo) O OSIRIS JSON é atualmente mantido por um único maintainer principal. Revisões e respostas são feitas em regime de melhor esforço e podem levar tempo dependendo da carga de trabalho. O foco é manter a especificação coerente, neutra em relação a vendors e estável enquanto o ecossistema inicial é construído.

Onde participar

Com o que você pode contribuir

Documentação (ponto de partida recomendado)

Melhorias na documentação são sempre valiosas e normalmente as mais rápidas de revisar:

• corrigir erros de digitação e links quebrados
• esclarecer a redação onde a spec for ambígua
• melhorar explicações e navegação entre páginas
• expandir orientações sobre “como validar” ou “como ler um documento OSIRIS JSON”

Exemplos

Você pode contribuir:

• propondo novos cenários de exemplo
• melhorando a legibilidade e a consistência dos exemplos existentes
• adicionando comentários ou notas de apoio que ajudem os leitores a entender por que determinados campos estão presentes

Especificação e schema

Para contribuições relacionadas a spec/schema:

• abra uma issue descrevendo a mudança e a motivação
• inclua um exemplo mínimo que demonstre o problema
• proponha a menor mudança possível que preserve compatibilidade

Como manter contribuições fáceis de revisar

• Prefira PRs pequenos e focados.
• Evite misturar mudanças sem relação entre si (por exemplo, refactor + nova funcionalidade no mesmo PR).
• Mantenha a linguagem precisa (declarações normativas devem usar MUST/SHOULD/MAY apenas quando apropriado).
• Se uma mudança puder afetar compatibilidade, destaque isso explicitamente na descrição do PR.

Contribuidores

Este projeto é atualmente mantido por um único maintainer principal. Os contribuidores serão listados aqui e na página de maintainer ao longo do tempo.

Code of Conduct

A participação na comunidade OSIRIS JSON é regida pelo Code of Conduct.
Leia o Code of Conduct

Contribuições assistidas por IA (permitidas, mas com responsabilidade)

Usar IA como apoio não tem problema. O que não é aceitável é produzir issues/PRs em massa sem entender o projeto.

Se você usar IA:

• Você é responsável pela correção e pelo escopo
• Leia e entenda o código/spec que está alterando
• Valide as saídas (tests, linters, validação de schema, exemplos)
• Não abra issues “especulativas” que você não tenha reproduzido
• Evite refactors casuais que renomeiem/reformatem grandes áreas sem propósito

Maintainers podem encerrar sem discussão prolongada:

• Issues duplicadas
• Issues sem passos/contexto reproduzíveis
• PRs claramente de baixo esforço, gerados automaticamente ou desalinhados com a direção do projeto

Primeiros passos

1. Faça um fork do repo e clone o seu fork
2. Crie uma branch no seu fork:
   • feat/<short-topic> or fix/<short-topic>
3. Faça suas mudanças em commits pequenos
4. Abra um Draft PR cedo se quiser feedback
5. Marque como pronto quando:
   • Tests pass
   • Docs/examples updated
   • A descrição do PR estiver completa

Checklist de Pull Request

Inclua na descrição do seu PR:

• What este PR altera?
• Why ele é necessário? (link para issue/discussion)
• How você o testou?
• Há alguma breaking change?

Checklist

• Relacionei a issue/discussion relevante (ou expliquei por que não existe)
• Mantive o escopo focado e evitei mudanças sem relação
• Adicionei/atualizei tests (se aplicável)
• Atualizei docs/examples (se aplicável)
• Executei formatting/linking/tools usados por este repo (se aplicável)

Mensagens de commit (recomendado)

Use mensagens claras, opcionalmente Conventional Commits:

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

Licenciamento

Ao contribuir, você concorda que suas contribuições são licenciadas sob a licença do projeto.

GSoC (ou programas similares)

Se você estiver contribuindo pensando em uma candidatura:

• Foque em uma área relevante
• Mostre que você consegue se comunicar com clareza, entregar pequenas melhorias e iterar com base em feedback
• Um design doc curto ou uma discussão de proposta vale mais do que muitos PRs de baixo impacto