Como preparar e enviar sua contribuição.

01 / O QUE CABE NA COLABORAÇÃO

Uma tarefa com começo, fim e valor próprio.

• Priorize oportunidades sinalizadas: escolha uma issue com help wanted, good first issue ou colabore. Uma pendência no roadmap não é, por si só, convite para implementar.
• Exemplos adequados: corrigir um guia reproduzido, escrever um exemplo isolado, testar um fluxo combinado em outro ambiente, melhorar a acessibilidade de uma página ou corrigir um defeito pontual com reprodução.
• Descreva as fronteiras: informe o resultado, os arquivos ou módulos envolvidos, os critérios de aceite e o que está fora da tarefa. Se depender de decisão, API ou funcionalidade ainda não pronta, sinalize antes de começar.
• Preserve a trilha principal: não assuma mudanças de arquitetura, protocolo, versão, release, distribuição, dependências estruturais ou reorganização ampla sem escopo explicitamente aprovado.
• Se a tarefa crescer: registre o novo problema na issue e proponha uma divisão. Não acrescente trabalho silenciosamente ao PR nem transforme a ajuda em pré-requisito da próxima entrega.
• Disponibilidade é voluntária: não há prazo presumido. Se precisar interromper, deixe um resumo do estado e avise na issue para que a tarefa possa ser retomada.

02 / ANTES DO CÓDIGO

Combine o que vai entregar na issue.

1. Leia a issue inteira, os comentários, os PRs vinculados e a documentação da área. Confira se alguém já está trabalhando nela.
2. Comente sua intenção, a abordagem, os arquivos prováveis, o ambiente disponível e como pretende verificar o resultado. Cite qualquer requisito ou hardware que não tenha.
3. Espere o mantenedor confirmar o escopo e a atribuição. Um comentário de interesse não reserva a tarefa automaticamente.
4. Para uma proposta nova, abra uma issue no repositório correspondente com problema, reprodução, comportamento esperado, escopo pequeno e critérios de aceite. Combine a proposta antes de implementar.
5. Mantenha decisões e dúvidas técnicas na issue ou no PR. Se conversar pelo Discord, registre o acordo no GitHub para que a revisão tenha o contexto.

Um bom alinhamento: “Quero reproduzir o guia X na versão Y, corrigir apenas os passos A e B e anexar comandos e capturas. Não vou alterar a IDE nem o fluxo de publicação.”

03 / TRABALHE NO SEU AMBIENTE

Repositório certo, fork próprio e uma branch por tarefa.

• IDE: código, documentação da IDE e testes vão para KineinVectis ↗. Siga o CONTRIBUTING da IDE ↗, a ordem de leitura pública e o guia de ambiente da versão atual.
• Site: páginas, acessibilidade, conteúdo autoral e navegação vão para KineinSite ↗. Use Node.js 24, o package-lock.json existente, npm ci e npm run dev.
• Faça um fork, atualize a base a partir de main do projeto e crie uma branch descritiva para a issue. Faça seus commits e envie a branch para seu próprio fork.
• Registre sistema, arquitetura, versão da IDE ou commit de origem e ferramentas usadas. Não presuma que o que funciona no seu ambiente já foi validado nos demais.
• Use projetos de teste e dados fictícios. Não altere a máquina, configuração, firmware, arquivos ou credenciais do mantenedor. Testes com hardware exigem equipamento próprio ou autorização explícita do responsável.

04 / DURANTE A MUDANÇA

Um diff pequeno e fiel às regras do projeto.

• Faça uma mudança coerente por PR. Não misture correção com reformatação geral, renomeações, atualização de dependências ou refatorações sem relação com a issue.
• Reaproveite os componentes, tokens e padrões existentes. Não acrescente biblioteca, serviço, cadastro, telemetria ou instalação automática sem alinhamento.
• Na IDE, identificadores ficam em inglês; a documentação atual usa português, e os comentários seguem o estilo do arquivo. Respeite a separação entre contrato, core, ponte C++, controller e view e os limites de arquitetura documentados.
• No site, use sitePath() para links internos, os tokens de tema e os componentes compartilhados. Preserve teclado, leitura no celular, movimento reduzido e os estados “disponível”, “em desenvolvimento” e “planejado”.
• Não desligue testes, gates, avisos ou verificações de segurança para fazer a entrega passar. Uma exceção exige diagnóstico, justificativa e revisão explícita.
• Não envie segredos, dados de terceiros, perfis pessoais de teste, diretórios locais, builds ou logs sem revisão. Use apenas conteúdo público e material que você tenha direito de contribuir.
• Se usar IA, revise cada alteração e execute você mesmo as verificações. Você continua responsável pelo conteúdo e deve conseguir explicar o código e as provas. Não envie uma saída de agente sem revisão.

Convenções completas da IDE: código, testes, commits e documentação ↗.

05 / O QUE PRECISA SER PROVADO

Explique como verificar, inclusive o que não funcionou.

• Correção de defeito: registre uma reprodução anterior, o resultado esperado e o resultado após a mudança. Quando houver código, inclua o teste de regressão adequado ao comportamento.
• IDE: siga os gates vigentes do repositório e da issue. O fluxo rápido é bash scripts/verificar.sh --rapido; a camada rápida de CI, quando indicada, usa bash scripts/verificar.sh --ci-rapida --estrito. Mudanças de UI, C++, protocolo ou hardware podem exigir outras camadas; o rápido sozinho não comprova tudo.
• Site: execute npm run build:pages. Para mudanças visuais ou de interação, execute também npm run check:browser com Chrome/Chromium disponível e confira larguras estreita, intermediária e larga, teclado, temas e movimento reduzido.
• Conteúdo executável: execute todos os comandos e exemplos no ambiente declarado, confira saídas e exercícios e informe as versões. No site, mudanças em estudos exigem npm run check:examples; guias da IDE seguem o roteiro de captura e a curadoria do repositório.
• Limites do ambiente: ferramenta ausente, teste não executado e hardware indisponível devem aparecer como não provados, com motivo. Não apresente omissão, simulação ou falha como aprovação.
• Se houver falha anterior: reproduza na base, identifique o comando e diferencie da regressão da sua alteração. Não corrija outro domínio ou altere a linha de base só para limpar o relatório.
• CI: informe o link e a execução que correspondem ao commit enviado. Um workflow que não iniciou ou foi bloqueado não é prova de teste aprovado. A decisão de revisão continua com o mantenedor.

Consulte os gates e seus requisitos ↗ antes de escolher as verificações. O ambiente e os comandos podem evoluir no repositório.

06 / EVIDÊNCIAS PARA A REVISÃO

O mantenedor precisa conseguir reproduzir.

• Informe data, sistema, arquitetura, versão ou commit, ferramentas e pré-requisitos. Descreva os passos na ordem em que foram executados.
• Liste cada comando relevante com resultado e limitações. Para falhas, inclua a mensagem necessária ao diagnóstico; para desempenho, método de medição e números comparáveis antes/depois.
• Para interface, anexe capturas antes/depois com o mesmo enquadramento e indique largura, tema e gesto testado. Um vídeo curto ajuda quando o problema depende de uma sequência de ações.
• Para hardware, registre placa, SDK, conexão, procedimento e resultado. Identifique claramente o que foi observado em hardware e o que foi apenas simulado.
• Anexe evidências à issue ou ao PR, ou use links públicos acessíveis. Um caminho no seu computador ou a frase “testado aqui” não permite revisão.
• Antes de anexar logs ou capturas, remova tokens, senhas, endereços privados e informações pessoais. Preserve os dados técnicos necessários para a reprodução.

07 / CONTEÚDO E REGISTRO

Documente no lugar certo, sem criar outra fonte de verdade.

• Explique o que mudou e por quê. Se a pessoa usuária vê outro comportamento, atualize a documentação correspondente à versão e ao escopo aprovado.
• Use fontes primárias, texto autoral e links verificáveis. Cite ferramenta, plataforma, padrão de linguagem e data do teste quando relevantes. Não prometa recursos futuros como se já estivessem disponíveis.
• O manual exibido no site é uma cópia verificada da IDE: a correção nasce no repositório da IDE e chega ao site pela sincronização; não edite a cópia para contornar a origem.
• Quando a regra da IDE exigir registro de entrega, roadmap ou contrato, combine os trechos compartilhados com o mantenedor. Inclua a atualização ou proposta no PR; não reorganize a fila principal nem atribua números de entregas concorrentes por conta própria.
• Liste trabalho pendente e decisões necessárias. Uma contribuição parcial deve dizer exatamente o que falta, sem transformar isso em obrigação para a próxima etapa da IDE.

08 / COMO ENVIAR AO MANTENEDOR

Abra um pull request no projeto correspondente.

1. Revise git diff e git status. Retire arquivos sem relação com a tarefa e confira se a branch contém apenas sua contribuição.
2. Organize commits por mudança verificável, com mensagem que explique o resultado. Na IDE, siga a convenção oficial de tipo e área; não envie commits incompletos como se estivessem prontos.
3. Envie a branch para seu fork e abra um PR direcionado a main do repositório correto. Use título concreto, por exemplo: “docs: corrigir a reprodução do primeiro projeto Python”.
4. Vincule a issue na descrição. Use Closes #número apenas quando a entrega resolver integralmente a issue do mesmo repositório; para progresso parcial, use Refs #número e explique o restante.
5. Preencha o modelo abaixo e preserve também os campos do template do repositório. Inclua provas, arquivos principais, limitações e instruções de revisão.
6. Se faltar escopo combinado, validação ou documentação, abra como rascunho / Draft. Quando estiver completo, marque pronto para revisão e aguarde o mantenedor.
7. A publicação e o merge no projeto oficial ficam com o mantenedor. Não publique release, tag, AppImage ou atualização do site em nome do projeto por conta própria.

09 / COPIE PARA A DESCRIÇÃO DO PR

Modelo de entrega.

Substitua cada campo pelo que aconteceu de fato. Quando algo não se aplicar, explique brevemente; não marque uma prova que você não executou.

## Tarefa e alinhamento
Issue: #...
Escopo combinado: ...
Repositório / versão ou commit de base: ...

## Problema e resultado
Antes: ...
Depois: ...
Critérios de aceite atendidos: ...

## Independência da trilha principal
Por que esta entrega pode ser revisada e integrada separadamente: ...
Dependências, decisões pendentes e mudanças fora do escopo: ...

## O que mudou
Arquivos / módulos principais e motivo: ...
Documentação atualizada: ...

## Como reproduzir
Sistema / arquitetura / ferramentas / versões: ...
Pré-requisitos: ...
Passos e resultado esperado: ...

## Validação executada
- Comando ou teste: ...
  Resultado / data: ...
- Evidências antes/depois: ...
- CI referente ao commit enviado, se executou: ...

## Não provado e limitações
Testes não executados e motivo: ...
Falhas anteriores à mudança, se houver: ...
Riscos ou trabalho restante: ...

## Revisão e autoria
Onde o mantenedor deve começar a revisão: ...
Participantes / coautores e contribuição de cada um: ...
Ferramentas de IA usadas, se houver, e o que foi revisado e testado: ...

10 / DEPOIS DO ENVIO

Revisão, integração e reconhecimento.

• Responda aos comentários no próprio PR. Explique decisões e atualize as provas se a correção alterar o resultado. Um pedido de mudança não autoriza ampliar o escopo.
• Se a base avançar ou houver conflito, alinhe a atualização e preserve o trabalho alheio. Não reescreva o histórico de outras pessoas nem use o conflito como oportunidade para refatorar outro domínio.
• O mantenedor pode pedir ajustes, adiar ou recusar a integração por escopo, qualidade, compatibilidade ou prioridade. Não há prazo garantido de revisão ou promessa de merge.
• A tarefa só conta como realizada quando for aceita e encerrada como concluída. Se a entrega exigir PR, o mantenedor confirma a integração antes desse encerramento. Cancelamentos e duplicidades não viram créditos de entrega.
• Mantenha a autoria correta nos commits e cite coautores e participantes no PR. Não atribua a si trabalho de outra pessoa nem inclua nome ou contato privado de terceiros sem consentimento.
• A seção de agradecimentos do site usa o perfil público do GitHub de quem possui commits na branch principal. A atualização pode demorar e depende da associação da autoria feita pelo GitHub. Relatos, revisões e testes sem commit podem receber um agradecimento revisado pelo mantenedor, com referência pública à ajuda prestada.
• Contribuições à IDE seguem a licença dupla MIT/Apache-2.0 indicada no repositório. Para o site e seus recursos visuais, confira os termos próprios; publicar uma imagem no GitHub não concede permissão para reutilizar material de terceiros.

11 / CONFERÊNCIA ANTES DE PEDIR REVISÃO

Sua entrega está pronta para ser avaliada?

• A issue e o escopo foram alinhados com o mantenedor.
• A contribuição é independente e não bloqueia a trilha principal.
• O PR aponta para o repositório e a branch corretos.
• O diff contém apenas mudanças necessárias à tarefa.
• Problema, resultado e critérios de aceite estão descritos.
• Ambiente, comandos, resultados e evidências permitem reprodução.
• Testes não executados, falhas e limitações estão explícitos.
• A documentação correspondente e a autoria estão corretas.
• Não há segredos, dados privados ou material sem permissão.
• Nenhum gate foi contornado e nenhuma publicação foi feita em nome do projeto.