Programma Lezione 242 di 250 · Progetto finale: rilascialo (impacchetta il tuo progetto)
Progetto finale: rilascialo (impacchetta il tuo progetto)

README + esecuzione con un solo comando

Hai una struttura pulita e test veri. L'ultimo miglio è la parte che i revisori incontrano davvero per prima: il README e l'unico comando che fa girare la cosa. Un progetto che richiede dieci minuti di tentativi per partire sembra rotto anche quando funziona. Un progetto che puoi clonare e far girare con una sola riga sembra professionale anche quando è piccolo. Stesso codice -> impressione completamente diversa.

Il README è un contratto. Un lettore lo scorre dall'alto in basso, e si aspetta una forma prevedibile: il nome del progetto come titolo, poi come installarlo, poi come usarlo, poi come testarlo. In concreto, un README solido ha una riga di titolo di primo livello (# Something), poi queste sezioni in quest'ordine:

# Triage Copilot

## Setup
pip install -e .            # editable install
cp .env.example .env        # then paste your real key into .env

## Usage
python -m triage            # the one-command run

## Tests
pytest

L'ordine conta perché un lettore lo segue come una serie di passi. Usage prima di Setup confonde -> non puoi usare ciò che non hai installato. Quindi scrivi un controllore, validate_readme(text), che restituisce True solo se compare un titolo # , seguito da ## Setup, poi ## Usage, poi ## Tests, ciascuno dopo il precedente. Una sezione mancante, o sezioni fuori ordine, restituiscono False. Il trucco: percorri le righe una volta, tieni un "cursore" di dove sei, e pretendi che ogni sezione compaia in una posizione dopo il cursore.

L'esecuzione con un solo comando. Nota che la riga ## Usage qui sopra è un solo comando. È l'obiettivo di un target di Makefile o di justfile come make run -> un solo comando facile da ricordare che avvia il progetto, così nessuno deve ricordare l'invocazione completa. Scrivi make_run(name) che restituisce quella stringa di comando per un progetto, per esempio python -m triage (o make run). Deve contenere il nome del progetto, normalizzato allo stesso modo della cartella del package, così un progetto diverso dà un comando diverso.

Due note oneste, non valutate, per il repository vero. Primo, i segreti: il passo cp .env.example .env esiste perché la tua vera chiave API va in .env, che aggiungi a .gitignore e di cui non fai mai commit. Fai commit solo di .env.example -> la forma della configurazione con valori segnaposto. Far trapelare una chiave in un repository pubblico è il classico errore dei progetti di portfolio. Secondo, rilasciarlo: per metterlo online scriveresti un piccolo Dockerfile (copia il repository, pip install, imposta il comando di esecuzione come entrypoint) e faresti push su una PaaS come Render, Railway o Fly. Quella parte non può girare né essere valutata nel tuo browser -> è tua da fare quando pubblichi. Premi Run per validare un README completo e stampare il comando di esecuzione.

Tocca a te

Scrivi i due pezzi deterministici di un buon README. validate_readme(text) restituisce True se e solo se compare un titolo di primo livello # , poi ## Setup, poi ## Usage, poi ## Tests, ciascuno dopo il precedente (una sezione mancante o sezioni fuori ordine -> False). make_run(name) restituisce la stringa di esecuzione con un solo comando (per esempio python -m <pkg> o make run) che contiene il nome del progetto, normalizzato come la cartella del package, così un nome diverso dà un comando diverso.

Hai notato un problema in questa lezione? Segnalalo · Chiedi qualcosa su questa lezione

Questo esercizio si apre presto

Finisci la lezione precedente e questa si sblocca. L'intero corso è gratuito, senza account, e puoi leggere questa lezione subito.