Contribuire al kernel semantico

È possibile contribuire al kernel semantico inviando problemi, avviando discussioni e inviando richieste pull. Il contributo al codice è molto apprezzato, ma la semplice archiviazione di problemi riscontrati è anche un ottimo modo per contribuire perché ci aiuta a concentrare i nostri sforzi.

Segnalazione di problemi e commenti

Microsoft accoglie sempre i report sui bug, le proposte di API e il feedback complessivo. Poiché si usa GitHub, è possibile usare le schede Problemi e Discussioni per avviare una conversazione con il team. Di seguito sono riportati alcuni suggerimenti quando si inviano problemi e commenti e suggerimenti in modo da poter rispondere al feedback il più rapidamente possibile.

Segnalazione di problemi

È possibile segnalare nuovi problemi per l'SDK nell'elenco dei problemi, ma prima di segnalare un nuovo problema, cercare nell'elenco dei problemi per assicurarsi che non esista già. Se si verificano problemi con la documentazione del kernel semantico (questo sito), segnalare un problema nel repository della documentazione del kernel semantico.

Se si trova un problema esistente per ciò che si vuole segnalare, includere il proprio feedback nella discussione. Consigliamo vivamente anche l'up-voting (👍 reazione) del post originale, in quanto ciò ci aiuta a classificare in ordine di priorità i problemi popolari nel backlog.

Scrittura di un report di bug valido

I report di bug validi semplificano la verifica e la causa radice del problema sottostante per i gestori. Migliore è un report sui bug, più velocemente il problema può essere risolto. Idealmente, un report sui bug deve contenere le informazioni seguenti:

• Descrizione generale del problema.
• Una riproduzione minima, ovvero la dimensione minima di codice/configurazione necessaria per riprodurre il comportamento errato.
• Descrizione del comportamento previsto, in contrasto con il comportamento effettivo osservato.
• Informazioni sull'ambiente: sistema operativo/distribuzione, architettura della CPU, versione dell'SDK e così via.
• Altre informazioni, ad esempio, si tratta di una regressione rispetto alle versioni precedenti? Esistono soluzioni alternative note?

Problema di creazione

Invio dei commenti e suggerimenti in corso

Se hai un feedback generale su Semantic Kernel o idee su come migliorarlo, condividilo nel nostro consiglio di discussione. Prima di iniziare una nuova discussione, cercare nell'elenco delle discussioni per assicurarsi che non esista già.

È consigliabile usare la categoria ideas se si ha un'idea specifica che si vuole condividere e la categoria Q&A se si ha una domanda sul kernel semantico.

È anche possibile avviare discussioni (e condividere eventuali commenti e suggerimenti creati) nella community Discord aggiungendosi al server Semantic Kernel Discord.

Avviare una discussione

Aiutaci a classificare in ordine di priorità il feedback

Attualmente si usano i voti per definire la priorità dei problemi e delle funzionalità nel backlog, quindi si prega di votare eventuali problemi o discussioni che si desidera visualizzare risolti.

Se pensi che altri potrebbero trarre vantaggio da una funzionalità, ti invitiamo anche a chiedere ad altri di votare il problema. Ciò consente di classificare in ordine di priorità i problemi che influiscono sulla maggior parte degli utenti. È possibile chiedere ai colleghi, agli amici o alla community su Discord di votare un problema condividendo il collegamento al problema o alla discussione.

Invio di richieste pull

Sono benvenuti i contributi al kernel semantico. Se si dispone di una correzione di bug o di una nuova funzionalità che si vuole contribuire, attenersi alla procedura seguente per inviare una richiesta pull. Successivamente, i gestori del progetto esamineranno le modifiche al codice e le uniranno dopo l'accettazione.

Flusso di lavoro di contributo consigliato

È consigliabile usare il flusso di lavoro seguente per contribuire al kernel semantico (si tratta dello stesso flusso di lavoro usato dal team del kernel semantico):

1. Creare un problema per il lavoro.
   • È possibile ignorare questo passaggio per modifiche semplici.
   • Riutilizzare un problema esistente nell'argomento, se presente.
   • Ottenere un accordo dal team e dalla community che la modifica proposta è una valida usando la discussione nel problema.
   • Indicare chiaramente nel problema che si assumerà l'implementazione. Questo ci consente di assegnare il problema all'utente e assicura che qualcun altro non funzioni accidentalmente su di esso.
2. Creare un fork personale del repository in GitHub (se non ne è già disponibile uno).
3. Nel fork creare un ramo di main (git checkout -b mybranch).
   • Denominare il ramo in modo che comunichi chiaramente le proprie intenzioni, ad esempio "issue-123" o "githubhandle-issue".
4. Apportare ed eseguire il commit delle modifiche nel ramo.
5. Aggiungere nuovi test corrispondenti alla modifica, se applicabile.
6. Compilare il repository con le modifiche apportate.
   • Assicurarsi che le compilazioni siano pulite.
   • Assicurarsi che i test superino tutti, inclusi i nuovi test.
7. Creare una richiesta pull per il ramo principale del repository.
   • Nella descrizione il problema o il miglioramento che sta risolvendo la modifica.
   • Verificare che tutti i controlli di integrazione continua vengano superati.
8. Attendere il feedback o l'approvazione delle modifiche dai gestori del codice.
9. Quando i proprietari dell'area hanno effettuato la disconnessione e tutti i controlli sono verdi, la richiesta pull verrà unita.

Dos and Don'ts while contributor

Di seguito è riportato un elenco di Dos e Don'ts che è consigliabile quando si contribuisce al kernel semantico per consentirci di esaminare e unire le modifiche il più rapidamente possibile.

Eseguire le operazioni seguenti:

• Seguire lo stile di codifica .NET standard e lo stile del codice Python
• Assegnare priorità allo stile corrente del progetto o del file che si sta modificando se differisce dalle linee guida generali.
• Includere test quando si aggiungono nuove funzionalità. Quando si correggeno i bug, iniziare con l'aggiunta di un test che evidenzia come il comportamento corrente viene interrotto.
• Mantenere incentrate le discussioni. Quando viene visualizzato un argomento nuovo o correlato, spesso è preferibile creare un nuovo problema che tenere traccia della discussione.
• Fare chiaramente stato su un problema che si sta per prendere in considerazione l'implementazione.
• Fai blog e/o tweet sui tuoi contributi!

Sconsigliate:

• Non sorprendere il team con grandi richieste pull. Vogliamo supportare i collaboratori, quindi consigliamo di presentare un problema e avviare una discussione in modo da poter concordare una direzione prima di investire una grande quantità di tempo.
• Non eseguire il commit del codice che non è stato scritto. Se si ritiene che il codice sia adatto per l'aggiunta al kernel semantico, inviare un problema e avviare una discussione prima di procedere.
• Non inviare richieste pull che modificano i file o le intestazioni correlati alle licenze. Se si ritiene che ci sia un problema con loro, inviare un problema e saremo lieti di discuterne.
• Non creare nuove API senza presentare un problema e discutere prima con il team. L'aggiunta di una nuova superficie di superficie pubblica a una biblioteca è un grosso problema e vogliamo assicurarci di ottenerla correttamente.

Modifiche di rilievo

I contributi devono mantenere la firma dell'API e la compatibilità comportamentale. Se si vuole apportare una modifica che interromperà il codice esistente, segnalare un problema per discutere l'idea o modificare se si ritiene che venga garantita una modifica di rilievo. In caso contrario, i contributi che includono modifiche di rilievo verranno rifiutati.

Processo di integrazione continua

Il sistema di integrazione continua (CI) eseguirà automaticamente le compilazioni necessarie ed eseguirà i test (inclusi quelli da eseguire localmente) per le richieste pull. Le compilazioni e le esecuzioni di test devono essere pulite prima di poter unire una richiesta pull.

Se la compilazione CI non riesce per qualsiasi motivo, il problema della richiesta pull verrà aggiornato con un collegamento che può essere usato per determinare la causa dell'errore in modo che possa essere risolto.

Contributi alla documentazione

Si accettano anche contributi al repository della documentazione del kernel semantico.