Aggiungi il primo esercizio

Il primo esercizio di ogni track è un esercizio "Hello, World!" molto semplice.

Lo scopo di questo esercizio è verificare rapidamente che tutto sia collegato correttamente. Questo confermerà che l'utente ha installato correttamente l'ambiente di programmazione, che sa come eseguire i test ed è in grado di farli passare. Oltre a questo, nel caso del client a riga di comando di Exercism (CLI), garantisce anche che la CLI sia installata e configurata correttamente e che il sito consegni i file giusti per l'esercizio senza inviare artefatti superflui. Infine, garantisce che l'utente abbia familiarità con il ciclo di scaricare un esercizio usando la CLI, risolvere un problema nel proprio ambiente di sviluppo locale e inviare la propria soluzione al sito.

In altre parole, non si tratta ancora davvero di imparare qualcosa sul linguaggio in sé. Il nostro obiettivo è qualcosa di estremamente semplice.

Questa sarà probabilmente anche la parte più difficile per impostare correttamente il repository del track, perché sono molti gli elementi in gioco nell'implementare un esercizio.

Implementare l'esercizio

All'esercizio "Hello, World!" si applicano alcune regole speciali:

• È sempre il primo esercizio di un track
• Ogni track deve implementarlo
• Il file di test contiene un solo test
• Il file stub contiene un'implementazione quasi funzionante, ma al posto di "Hello, World!" usa "Goodbye, Mars!"
• Non ha prerequisites
• Non ha practices

Determinare i percorsi dei file

L'esercizio "Hello, World!" (e in realtà tutti gli esercizi su Exercism) richiede un insieme specifico di file:

• Documentazione: spiega allo studente cosa deve fare (può essere generata automaticamente).
• Metadati: fornisce a Exercism alcuni metadati sull'esercizio (possono essere in gran parte generati automaticamente).
• Suite di test: verifica la correttezza di una soluzione (specifica del track).
• Implementazione stub: fornisce un punto di partenza per gli studenti (specifica del track).
• Implementazione di esempio: fornisce un'implementazione di esempio che supera tutti i test (specifica del track).
• File aggiuntivi: assicurano che i test possano essere eseguiti (specifici del track, opzionali).

Prima di poter creare l'esercizio "Hello, World!", devi prendere alcune decisioni sui nomi e sui percorsi dei file specifici del track (suite di test, implementazione stub, implementazione di esempio ed eventuali file aggiuntivi).

La regola generale è usare nomi idiomatici per il linguaggio. Dove non ci sono preferenze forti, preferisci strutture di directory poco profonde. L'implementazione di esempio dovrà essere identificabile dallo script di CI, quindi è consigliabile scegliere un nome di base generico che tutti gli esercizi possano usare, ad esempio example, sample o reference-solution.

Configurare i percorsi dei file

Dopo aver scelto i percorsi dei file specifici del track, dovresti configurarli nella chiave files del file config.json nella radice. La chiave files servirà da modello per tutti gli esercizi, così che qualsiasi strumento (e ne useremo alcuni tra poco) sappia dove cercare i file. Puoi usare vari segnaposto per configurare facilmente lo slug dell'esercizio (hello-world in questo caso).

Esempio

Se il tuo track usa il PascalCase per i suoi file, la chiave files potrebbe apparire così:

"files": {
  "solution": [
    "%{pascal_slug}.cs"
  ],
  "test": [
    "%{pascal_slug}Tests.cs"
  ],
  "example": [
    ".meta/Example.cs"
  ]
}

Per maggiori informazioni, consulta la documentazione sulla chiave files.

Creare i file

Dopo aver specificato i modelli dei percorsi dei file, puoi creare rapidamente i file dell'esercizio "Hello, World!" eseguendo i seguenti comandi dalla directory radice del track:

bin/fetch-configlet
bin/configlet create --practice-exercise hello-world

Impostare l'autore

Per far sì che il sito ti elenchi come autore dell'esercizio, segui questi passaggi:

Nel file .meta/config.json dell'esercizio:

• Aggiungi il tuo nome utente GitHub alla chiave authors

Perché questo funzioni, dovrai collegare il tuo account Exercism a GitHub. Puoi farlo sul sito, nella sezione Integrazioni della pagina Impostazioni.

Usare lo script

I repository dei track più recenti possono usare lo script bin/add-practice-exercise (sorgente) per aggiungere nuovi esercizi:

bin/add-exercise -a <github_username> two-fer

Implementare l'esercizio

Una volta creati i file dello scaffolding, dovrai:

• Aggiungere i test al file dei test
• Aggiungere un'implementazione di esempio
• Definire il contenuto del file stub

Aggiungere i test

Una parte fondamentale dell'aggiungere un esercizio è aggiungere i test. A grandi linee, ci sono due opzioni quando si implementa uno degli esercizi di cui sopra:

1. Implementare i test da zero, usando i casi di test dal canonical-data.json dell'esercizio
2. Trasferire i test dall'implementazione di un altro track (suggerimento: vai su https://exercism.org/exercises/hello-world per avere una panoramica di quali track hanno implementato un determinato esercizio).

Per l'esercizio "Hello, World!" ci sarà un solo caso di test, quindi entrambe le opzioni vanno bene.

Aggiungere un'implementazione di esempio

Il file dell'implementazione di esempio dovrebbe contenere il codice necessario per superare i test.

Definire lo stub

Il file stub dovrebbe avere una soluzione quasi funzionante ai test, ma con il testo "Hello, World!" sostituito da "Goodbye, Mars!". Suggerimento: puoi semplicemente copiare, incollare e modificare la soluzione di esempio.

Aggiornare gli autori dell'esercizio

Una volta terminato l'esercizio, aggiungi il tuo nome utente GitHub all'array "authors" nel file .meta/config.json dell'esercizio. Questo ci assicura di attribuirti correttamente la creazione dell'esercizio.

Linting

Per verificare che l'esercizio sia configurato correttamente, puoi usare la funzionalità di linting integrata nello strumento configlet.

Il primo passo è scaricare lo strumento configlet, per il quale abbiamo creato due script:

• bin/fetch-configlet: eseguilo quando usi *nix o macOS
• bin/fetch-configlet.ps1: eseguilo quando usi Windows

Eseguire uno di questi script dalla directory radice del repository del track scaricherà il binario bin/configlet o bin/configlet.exe, a seconda del caso.

Puoi quindi verificare la correttezza dell'esercizio eseguendo bin/configlet lint.

The `tags` array is empty:
/path/to/track/config.json