Aggiungere un esercizio di pratica

Questo documento spiegherà come aggiungere un nuovo esercizio pratico.

Selezionare un esercizio

Il modo più semplice per verificare quali esercizi pratici non sono ancora stati implementati è andare alla pagina di build della traccia (ad esempio https://exercism.org/tracks/csharp/build) e controllare la sezione "Esercizi pratici".

Caution

I dati nella pagina di build vengono aggiornati una volta al giorno.

Creare lo scheletro dell'esercizio

Puoi creare rapidamente lo scheletro di un nuovo esercizio pratico eseguendo lo script bin/add-practice-exercise (sorgente) dalla directory principale della traccia:

bin/add-practice-exercise <exercise-slug>

Se vuoi, puoi anche specificare la difficoltà dell'esercizio (tramite -d) e/o il nome utente GitHub dell'autore (tramite -a):

bin/add-practice-exercise -d 3 -a foobar <exercise-slug>
Note

Se stai lavorando a un repo di una traccia senza questo file, sentiti libero di copiarlo nel tuo repo usando il link al sorgente qui sopra.

Implementare l'esercizio

Una volta creati i file dello scheletro, dovrai:

  • Aggiungere i test al file dei test
  • Aggiungere un'implementazione di esempio
  • Definire il contenuto del file stub
  • Nel file .meta/config.json dell'esercizio:
    • Aggiungere il nome utente GitHub degli autori dell'esercizio alla chiave authors
  • Nel file config.json della traccia:
    • Controllare/aggiornare la difficoltà dell'esercizio
    • Aggiungere concetti alla chiave practices (necessario solo se la traccia ha esercizi concettuali)
    • Aggiungere concetti alla chiave prerequisites (necessario solo se la traccia ha esercizi concettuali)

Aggiungere i test

Una parte fondamentale dell'aggiunta di un esercizio è aggiungere i test. In linea di massima, ci sono due opzioni quando si aggiungono i test per un esercizio pratico:

  1. Implementare i test da zero, usando i casi di test dal file canonical-data.json dell'esercizio, come si trova nel repo problem-specifications.
  2. Portare i test dall'implementazione di un'altra traccia (suggerimento: vai su https://exercism.org/exercises/<slug> per avere una panoramica di quali tracce hanno implementato un dato esercizio).

La seconda opzione può essere particolarmente allettante, perché può darti risultati rapidamente. Tieni però presente che dovresti ritoccare l'implementazione per adattarla al meglio alla tua traccia. Ad esempio, alcune tracce non usano classi e lavorano solo con funzioni. Se invece la tua traccia di solito lavora con oggetti, dovresti adattare l'implementazione a ciò che si adatta meglio alla tua traccia.

Note

Alcune tracce usano un generatore di test per (ri)generare automaticamente i file di test di un esercizio. Controlla la documentazione della traccia per vedere se esiste un generatore di test e, in tal caso, come usarlo.

Aggiungere un'implementazione di esempio

Per garantire che sia possibile scrivere codice che superi i test, è necessario aggiungere un'implementazione di esempio.

Note

Il codice non deve essere idiomatico, deve solo superare i test.

Puoi verificare che l'implementazione di esempio superi tutti i test eseguendo lo script bin/verify-exercises (sorgente) dalla directory principale della traccia:

bin/verify-exercises <exercise-slug>

Usa l'output per verificare che l'implementazione di esempio superi tutti i test.

Note

Se stai lavorando a un repo di una traccia senza questo file, sentiti libero di copiarlo nel tuo repo usando il link al sorgente qui sopra.

Advanced

Dietro le quinte, lo script bin/verify-exercises fa diverse cose:

  • Copia l'esercizio in una directory temporanea
  • Sovrascrive i file stub con i file dell'implementazione di esempio
  • Se il file di test contiene test saltati, questi verranno «riattivati»
  • Esegue i test

Aggiungere i file stub

I file stub dell'implementazione forniscono un punto di partenza per gli studenti.

Consigliamo che i file stub contengano la quantità minima di codice affinché:

  • Lo studente possa iniziare subito a implementare la logica per superare i test
  • Lo studente non si trovi davanti a errori di sintassi «strani»

In pratica, questo significa definire le funzioni/metodi testati dalla suite di test. Le tracce sono libere di impostare questo codice come preferiscono, purché si assicurino che il codice stub inizialmente fallisca tutti i test.

Esempi

Python:

def two_fer(name):
    pass

Kotlin:

fun twofer(name: String): String {
    TODO("Implement the function to complete the task")
}

Eseguire il lint sull'esercizio

L'ultimo passo è eseguire il linter per verificare che i file (di configurazione) della traccia siano strutturati correttamente: sia sintatticamente che semanticamente.

Per prima cosa, assicurati di avere la versione più recente di configlet eseguendo:

bin/fetch-configlet

Poi esegui il linter con:

bin/configlet lint

Usa l'output per verificare che vada tutto bene.

Inviare una Pull Request

Una volta che tutto va bene, puoi inviare una Pull Request al repository della traccia.

Prima di inviare, leggi la guida alle Pull Request per i contributori e la guida alle Pull Request.

Assicurati che la descrizione della PR indichi l'esercizio che viene aggiunto.