Contribuire a Zoo Code

Zoo Code è un progetto guidato dalla comunità e apprezziamo profondamente ogni contributo. Per semplificare la collaborazione, operiamo su una base Issue-First, il che significa che tutte le Pull Request (PR) devono prima essere collegate a un'issue di GitHub. Si prega di leggere attentamente questa guida.

Sommario

• Prima di contribuire
• Trovare e pianificare il tuo contributo
• Processo di sviluppo e invio
• Aspettative sulle Pull Request
• Contributi assistiti da IA
• Legale

Prima di contribuire

1. Codice di condotta

Tutti i contributori devono attenersi al nostro Codice di condotta.

2. Roadmap del progetto

La nostra roadmap guida la direzione del progetto. Allinea i tuoi contributi a questi obiettivi chiave:

Affidabilità prima di tutto

• Assicurati che la modifica dei diff e l'esecuzione dei comandi siano costantemente affidabili.
• Riduci i punti di frizione che scoraggiano l'uso regolare.
• Garantisci un funzionamento fluido in tutte le localizzazioni e piattaforme.
• Espandi un supporto solido per un'ampia varietà di provider e modelli di intelligenza artificiale.

Esperienza utente migliorata

• Semplifica l'interfaccia utente/esperienza utente per chiarezza e intuitività.
• Migliora continuamente il flusso di lavoro per soddisfare le elevate aspettative che gli sviluppatori hanno per gli strumenti di uso quotidiano.

Leader nelle prestazioni degli agenti

• Stabilisci benchmark di valutazione completi (eval) per misurare la produttività nel mondo reale.
• Semplifica per tutti l'esecuzione e l'interpretazione di queste valutazioni.
• Fornisci miglioramenti che dimostrino chiari aumenti nei punteggi di valutazione.

Menziona l'allineamento con queste aree nelle tue PR.

3. Unisciti alla community di Zoo Code

• Discord: Unisciti al nostro Discord.
• Reddit: Unisciti al nostro Reddit.

Trovare e pianificare il tuo contributo

Tipi di contributi

• Correzioni di bug: risoluzione di problemi di codice.
• Nuove funzionalità: aggiunta di funzionalità.
• Documentazione: miglioramento di guide e chiarezza.

Approccio Issue-First

Tutti i contributi iniziano con un'issue di GitHub utilizzando i nostri modelli snelli.

• Controlla le issue esistenti: cerca nelle issue di GitHub.
• Crea un'issue utilizzando:
  • Miglioramenti: modello "Richiesta di miglioramento" (linguaggio semplice incentrato sul vantaggio per l'utente).
  • Bug: modello "Segnalazione di bug" (riproduzione minima + previsto vs effettivo + versione).
• Vuoi lavorarci? Commenta "Rivendico" sull'issue e invia un DM al team principale su Discord per essere assegnato. L'assegnazione verrà confermata nel thread.
• Le PR devono essere collegate all'issue. Le PR non collegate possono essere chiuse.

Decidere su cosa lavorare

• Controlla la pagina GitHub Issues per trovare le issues.
• Per la documentazione, visita Zoo Code Docs.

Segnalazione di bug

• Controlla prima le segnalazioni esistenti.
• Crea un nuovo bug utilizzando il modello "Segnalazione di bug" con:
  • Passaggi di riproduzione chiari e numerati
  • Risultato previsto vs effettivo
  • Versione di Zoo Code (obbligatoria); provider/modello di intelligenza artificiale se pertinente
• Problemi di sicurezza: segnala in privato tramite avvisi di sicurezza.

Processo di sviluppo e invio

Configurazione dello sviluppo

1. Esegui il fork e clona:

git clone https://github.com/YOUR_USERNAME/Zoo-Code.git

2. Installa le dipendenze:

pnpm install

3. Debug: apri con VS Code (F5).

Linee guida per la scrittura del codice

• Una PR mirata per funzionalità o correzione.
• Segui le migliori pratiche di ESLint e TypeScript.
• Scrivi commit chiari e descrittivi che facciano riferimento alle issue (ad es. Risolve #123).
• Fornisci test approfonditi (npm test).
• Esegui il rebase sul ramo main più recente prima dell'invio.

Invio di una Pull Request

• Inizia come bozza di PR se cerchi un feedback iniziale.
• Descrivi chiaramente le tue modifiche seguendo il modello di Pull Request.
• Collega l'issue nella descrizione/titolo della PR (ad es. "Risolve #123").
• Fornisci screenshot/video per le modifiche all'interfaccia utente.
• Indica se sono necessari aggiornamenti alla documentazione.

Politica sulle Pull Request

• Deve fare riferimento a un'issue di GitHub assegnata. Per essere assegnato: commenta "Rivendico" sull'issue e invia un DM al team principale su Discord. L'assegnazione verrà confermata nel thread.
• Le PR non collegate possono essere chiuse.
• Le PR devono superare i test di integrazione continua, essere in linea con la roadmap e avere una documentazione chiara.

Processo di revisione

• Triage giornaliero: controlli rapidi da parte dei manutentori.
• Revisione approfondita settimanale: valutazione completa.
• Itera prontamente in base al feedback.

Aspettative sulle Pull Request

Le Pull Request devono essere revisionabili, testate e manutenibili. Prima di aprire una PR, assicurati che:

• La modifica sia limitata a un issue, bug o miglioramento specifico.
• Tu possa spiegare cosa fa la modifica e perché è corretta.
• Tu abbia testato la modifica localmente dove pratico.
• Tu sia disposto a rispondere al feedback della revisione e ad apportare ragionevoli modifiche di follow-up.
• La PR non richieda ai manutentori di riscrivere, riprogettare o assumere sostanzialmente la proprietà dell'implementazione prima di poter essere unita.

I manutentori possono chiudere le PR che sono incomplete, troppo ampie, inattive, non allineate con la direzione del progetto o che creano un onere di revisione o manutenzione sproporzionato. La chiusura di una PR non è un giudizio sul contributore; è una decisione dei manutentori che la modifica non può essere accettata nella sua forma attuale.

Contributi assistiti da IA

L'uso di strumenti di IA è consentito, ma i contributori rimangono completamente responsabili delle loro contribuzioni.

Se utilizzi strumenti di IA per aiutare a creare una PR, devi:

• Revisionare e comprendere ogni modifica significativa.
• Essere in grado di spiegare l'implementazione e i compromessi con parole tue.
• Testare tu stesso la modifica. Se i test non sono praticamente fattibili nel tuo ambiente, spiega il motivo nella descrizione della PR e descrivi come i revisori possono verificare la modifica.
• Verificare che il codice generato sia corretto, necessario e compatibile con la licenza del progetto.
• Valuta di divulgare l'assistenza dell'IA nella descrizione della PR quando ha influenzato sostanzialmente il codice, i test o il design — questo aiuta i revisori a fornire un feedback migliore.

Si prega di non inviare modifiche generate dall'IA che non si comprendono o che non si possono mantenere durante la revisione. I manutentori possono chiudere le PR che sembrano sostanzialmente assistite dall'IA ma prive di verifica umana, motivazione chiara o adeguato seguito nella revisione.

Legale

Contribuendo, accetti che i tuoi contributi siano concessi in licenza con la licenza Apache 2.0, in coerenza con la licenza di Zoo Code.