Contribuindo para o kernel semântico

Você pode contribuir para o Kernel Semântico enviando problemas, iniciando discussões e enviando solicitações pull (PRs). Contribuir com código é muito apreciado, mas simplesmente arquivar problemas para problemas que você encontrar também é uma ótima maneira de contribuir, pois nos ajuda a concentrar nossos esforços.

Reportar problemas e comentários

Sempre aceitamos relatórios de bugs, propostas de API e feedback geral. Como usamos o GitHub, você pode usar as guias Problemas e Discussões para iniciar uma conversa com a equipe. Abaixo estão algumas dicas ao enviar problemas e comentários para que possamos responder aos seus comentários o mais rápido possível.

Comunicar problemas

Novos problemas para o SDK podem ser relatados em nossa lista de problemas, mas antes de registrar um novo problema, pesquise a lista de problemas para se certificar de que ele ainda não existe. Se você tiver problemas com a documentação do Kernel Semântico (este site), registre um problema no repositório de documentação do Kernel Semântico.

Se você encontrar um problema existente para o que você queria relatar, por favor, inclua seu próprio feedback na discussão. Também recomendamos que se vote (👍 reação) no post original, pois isso nos ajuda a priorizar questões populares em nossa lista de pendências.

Escrevendo um bom relatório de bug

Bons relatórios de bugs tornam mais fácil para os mantenedores verificar e causar o problema subjacente. Quanto melhor um relatório de bug, mais rápido o problema pode ser resolvido. Idealmente, um relatório de bug deve conter as seguintes informações:

• Uma descrição de alto nível do problema.
• Uma reprodução mínima, ou seja, o menor tamanho de código/configuração necessário para reproduzir o comportamento errado.
• Uma descrição do comportamento esperado, contrastado com o comportamento real observado.
• Informações sobre o ambiente: SO / distribuição, arquitetura de CPU, versão SDK, etc.
• Informações adicionais, por exemplo, É uma regressão de versões anteriores? Existem soluções alternativas conhecidas?

Criar problema

A submeter comentários

Se você tiver feedback geral sobre o Kernel Semântico ou ideias sobre como melhorá-lo, por favor, compartilhe-o em nosso quadro de discussões. Antes de iniciar uma nova discussão, pesquise a lista de discussões para se certificar de que ela ainda não existe.

Recomendamos usar a categoria de ideias se você tiver uma ideia específica que gostaria de compartilhar e a categoria de Perguntas e Respostas se tiver uma pergunta sobre o Kernel Semântico.

Você também pode iniciar discussões (e compartilhar qualquer feedback que tenha criado) na comunidade do Discord ingressando no servidor Discord do Kernel Semântico.

Iniciar uma discussão

Ajude-nos a priorizar o feedback

Atualmente, usamos votos positivos para nos ajudar a priorizar problemas e recursos em nossa lista de pendências, portanto, vote em todos os problemas ou discussões que você gostaria de ver abordados.

Se você acha que outras pessoas se beneficiariam de um recurso, também recomendamos que você peça a outras pessoas que votem favoravelmente o problema. Isso nos ajuda a priorizar os problemas que estão afetando a maioria dos usuários. Você pode pedir a colegas, amigos ou à comunidade no Discord que votem em um problema compartilhando o link para o problema ou discussão.

Envio de pull requests

Aceitamos contribuições para o Semantic Kernel. Se você tiver uma correção de bug ou um novo recurso que gostaria de contribuir, siga as etapas abaixo para enviar uma solicitação pull (PR). Depois, os mantenedores do projeto analisarão as alterações de código e as mesclarão assim que forem aceitas.

Fluxo de trabalho de contribuição recomendado

Recomendamos usar o seguinte fluxo de trabalho para contribuir com o Kernel Semântico (este é o mesmo fluxo de trabalho usado pela equipe do Kernel Semântico):

1. Crie um problema para o seu trabalho.
   • Você pode pular esta etapa para alterações triviais.
   • Reutilize um problema existente sobre o tema, se houver.
   • Obtenha o acordo da equipe e da comunidade de que a mudança proposta é boa usando a discussão na questão.
   • Indique claramente na questão que irá assumir a implementação. Isso nos permite atribuir o problema a você e garante que outra pessoa não trabalhe acidentalmente nele.
2. Crie uma bifurcação pessoal do repositório no GitHub (se ainda não tiver uma).
3. Na bifurcação, crie uma ramificação fora da principal (git checkout -b mybranch).
   • Nomeie a ramificação para que ela comunique claramente suas intenções, como "issue-123" ou "githubhandle-issue".
4. Faça e confirme suas alterações em sua filial.
5. Adicione novos testes correspondentes à sua alteração, se aplicável.
6. Crie o repositório com suas alterações.
   • Certifique-se de que as compilações estão limpas.
   • Certifique-se de que todos os testes estão a ser aprovados, incluindo os novos testes.
7. Crie uma RP na ramificação principal do repositório.
   • Indique na descrição qual o problema ou melhoria que a sua alteração está a abordar.
   • Verifique se todas as verificações de Integração Contínua estão passando.
8. Aguarde comentários ou aprovação de suas alterações por parte dos mantenedores de código.
9. Quando os proprietários da área tiverem assinado e todos os cheques estiverem verdes, seu RP será mesclado.

O que fazer e o que não fazer ao contribuir

A seguir está uma lista de Prós e Contras que recomendamos ao contribuir para o Kernel Semântico para nos ajudar a revisar e mesclar suas alterações o mais rápido possível.

Fazer:

• Siga o estilo de codificação .NET padrão e o estilo de código Python
• Dê prioridade ao estilo atual do projeto ou arquivo que você está alterando se ele divergir das diretrizes gerais.
• Inclua testes ao adicionar novos recursos. Ao corrigir bugs, comece adicionando um teste que destaca como o comportamento atual é quebrado.
• Mantenha as discussões focadas. Quando um tópico novo ou relacionado surge, muitas vezes é melhor criar um novo problema do que acompanhar a discussão.
• Indique claramente sobre uma questão que vai assumir ao implementá-la.
• Faça blog e/ou tweet sobre suas contribuições!

Não:

• Não surpreenda a equipe com grandes pedidos de atração. Queremos apoiar os contribuidores, por isso recomendamos que preencha um problema e inicie uma discussão para que possamos chegar a acordo sobre uma direção antes de investir uma grande quantidade de tempo.
• Não confirme código que você não escreveu. Se você encontrar um código que você acha que é uma boa opção para adicionar ao Kernel Semântico, arquive um problema e inicie uma discussão antes de prosseguir.
• Não envie RPs que alterem arquivos ou cabeçalhos relacionados ao licenciamento. Se você acredita que há um problema com eles, registre um problema e teremos prazer em discuti-lo.
• Não crie novas APIs sem registrar um problema e discutir com a equipe primeiro. Adicionar uma nova área de superfície pública a uma biblioteca é um grande negócio e queremos ter certeza de que acertamos.

Alterações Interruptivas

As contribuições devem manter a assinatura da API e a compatibilidade comportamental. Se você quiser fazer uma alteração que irá quebrar o código existente, por favor, registre um problema para discutir sua ideia ou alterar se você acredita que uma alteração de quebra é justificada. Caso contrário, as contribuições que incluam alterações de quebra serão rejeitadas.

O processo de integração contínua (IC)

O sistema de integração contínua (CI) executará automaticamente as compilações necessárias e executará testes (incluindo aqueles que você também deve executar localmente) para RPs. Compilações e execuções de teste devem estar limpas antes que um PR possa ser mesclado.

Se a compilação de CI falhar por qualquer motivo, o problema de RP será atualizado com um link que pode ser usado para determinar a causa da falha para que possa ser resolvido.

Contribuir para a documentação

Também aceitamos contribuições para o repositório de documentação do Kernel Semântico. Para saber como fazer contribuições, comece com o guia do colaborador do Microsoft docs.