Contribuindo para o kernel semântico

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

Como relatar problemas e comentários

Sempre recebemos 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.

Problemas de relatórios

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 garantir que ele ainda não exista. Se você tiver problemas com a documentação do Semantic Kernel (este site), registre um problema no repositório de documentação do Semantic Kernel.

Se você encontrar um problema existente para o que deseja relatar, inclua seu próprio feedback na discussão. Também recomendamos votar a favor (👍 reação) da postagem original, pois isso nos ajuda a priorizar questões populares em nosso backlog.

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 for um relatório de bug, mais rápido o problema poderá 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: sistema operacional/distribuição, arquitetura da CPU, versão do SDK, etc.
• Informações adicionais, por exemplo, é uma regressão de versões anteriores? Existem soluções alternativas conhecidas?

Criar problema

Enviar comentários

Se você tiver comentários gerais sobre o Kernel Semântico ou ideias sobre como melhorá-lo, compartilhe-o em nosso fórum de discussões. Antes de iniciar uma nova discussão, pesquise a lista de discussões para ter certeza 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 alguma dúvida 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 Semantic Kernel Discord.

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 quaisquer problemas ou discussões que você gostaria de ver resolvidos.

Se você acha que outras pessoas se beneficiariam de um recurso, também recomendamos que você peça a outras pessoas que votem a favor do 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 para votar a favor de um problema compartilhando o link para o problema ou discussão.

Enviando solicitações de pull

Agradecemos contribuições para o Kernel Semântico. Se você tiver uma correção de bug ou um novo recurso com o qual gostaria de contribuir, siga as etapas abaixo para enviar uma solicitação de pull (PR). Depois, os mantenedores do projeto revisarã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 (esse é o mesmo fluxo de trabalho usado pela equipe do Kernel Semântico):

1. Crie um problema para o seu trabalho.
   • Você pode ignorar esta etapa para alterações triviais.
   • Reutilize um problema existente sobre o tópico, se houver.
   • Obtenha a concordância da equipe e da comunidade de que sua mudança proposta é boa usando a discussão do problema.
   • Indique claramente na edição que você 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 você ainda não tiver uma).
3. Em sua bifurcação, crie uma ramificação de main (git checkout -b mybranch).
   • Nomeie o branch para que ele comunique claramente suas intenções, como "issue-123" ou "githubhandle-issue".
4. Faça e confirme suas alterações em seu branch.
5. Adicione novos testes correspondentes à sua alteração, se aplicável.
6. Construa o repositório com suas alterações.
   • Certifique-se de que as compilações estejam limpas.
   • Certifique-se de que todos os testes sejam aprovados, incluindo seus novos testes.
7. Crie uma PR no branch principal do repositório.
   • Indique na descrição qual problema ou melhoria sua alteração está abordando.
   • Verifique se todas as verificações de Integração Contínua estão sendo aprovadas.
8. Aguarde o feedback ou a aprovação de suas alterações dos mantenedores do código.
9. Quando os proprietários da área tiverem assinado e todas as verificações estiverem verdes, seu PR será mesclado.

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

Veja a seguir uma lista do que fazer e do que não fazer ao contribuir com o Semantic Kernel para nos ajudar a revisar e mesclar suas alterações o mais rápido possível.

O que fazer:

• Siga o estilo de codificação padrão do .NET 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 destaque como o comportamento atual é interrompido.
• Mantenha as discussões focadas. Quando um tópico novo ou relacionado surge, geralmente é melhor criar um novo problema do que desviar a discussão.
• Declare claramente sobre uma questão que você vai assumir ao implementá-la.
• Faça um blog e / ou tweet sobre suas contribuições!

Contras:

• Não surpreenda a equipe com grandes solicitações de pull. Queremos apoiar os colaboradores, por isso recomendamos registrar um problema e iniciar uma discussão para que possamos concordar com uma direção antes de investir muito tempo.
• Não confirme o código que você não escreveu. Se você encontrar um código que considere adequado para adicionar ao Semantic Kernel, registre um problema e inicie uma discussão antes de prosseguir.
• Não envie PRs que alterem arquivos ou cabeçalhos relacionados ao licenciamento. Se você acredita que há um problema com eles, registre um problema e ficaremos felizes 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 de quebra

As contribuições devem manter a assinatura da API e a compatibilidade comportamental. Se você quiser fazer uma alteração que interrompa o código existente, registre um problema para discutir sua ideia ou alteração se acreditar que uma alteração significativa é necessária. Caso contrário, as contribuições que incluem alterações significativas serão rejeitadas.

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

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

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

Contribuindo para a documentação

Também aceitamos contribuições para o repositório de documentação do Semantic Kernel.