Conteúdo do curso Lição 242 de 250 · Projeto Final: Ship It (Empacote Seu Projeto)
Projeto Final: Ship It (Empacote Seu Projeto)

README + Execução com um comando

Você tem um layout limpo e testes reais. A última milha é a parte que os revisores realmente acessam primeiro: o README e o comando único que executa a coisa. Um projeto que leva dez minutos de palpites para começar parece quebrado mesmo quando funciona. Um projeto que você pode clonar e rodar com uma única linha parece profissional mesmo quando é pequeno. Mesmo código -> impressão totalmente diferente.

O README é um contrato. Um leitor lê rapidamente de cima a baixo e espera um formato previsível: o nome do projeto como título, depois como instalar, depois como usar, depois como testar. Concretamente, um README forte tem uma linha de título de nível superior (# Something), depois estas seções nesta ordem:

# 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

A ordem importa porque um leitor a segue como passos. Uso antes de Setup é confuso -> você não pode usar o que não instalou. Então você escreve um checker, validate_readme(text), que retorna True apenas se um título #  aparecer, seguido por ## Setup, depois ## Usage, depois ## Tests, cada um após o anterior. Uma seção faltando, ou seções fora de ordem, retorna False. O truque: percorra as linhas uma vez, mantenha um "cursor" de onde você está, e exija que cada seção apareça em uma posição depois do cursor.

A execução de um comando. Note que a ## Usage linha acima é um comando único. Esse é o objetivo de um alvo de Makefile ou justfile como make run -> um comando memorável que inicia o projeto, para que ninguém precise lembrar da invocação completa. Escreva make_run(name) que retorna essa string de comando para um projeto, por exemplo python -m triage (ou make run). Ele deve incluir o nome do projeto, normalizado da mesma forma que o diretório do pacote, para que um projeto diferente resulte em um comando diferente.

Duas notas honestas, não avaliadas, para o repositório real. Primeiro, segredos: o cp .env.example .env passo existe porque sua chave de API real vai em .env, que você adiciona ao .gitignore e never commit. Você commita apenas .env.example -> o shape da configuração com valores de placeholder. Vazamento de uma chave para um repositório público é o erro clássico de projeto de portfólio. Segundo, deploying this: para colocá-lo online você escreveria um pequeno Dockerfile (copie o repositório, pip install, defina o comando de execução como o entrypoint) e faria o push para um PaaS como Render, Railway ou Fly. Essa parte não pode ser executada ou avaliada no seu navegador -> é sua para fazer quando você publicar. Pressione Run para validar um README completo e imprimir o comando de execução.

Sua vez

Escreva as duas partes determinísticas de um bom README. validate_readme(text) retorna True se um título #  de nível superior aparecer, depois ## Setup, depois ## Usage, depois ## Tests, cada um após o anterior (uma seção ausente ou seções fora de ordem -> False). make_run(name) retorna a string de execução de um comando (ex. python -m <pkg> ou make run) que incorpora o nome do projeto, normalizado como o diretório do pacote, então um nome diferente gera um comando diferente.

Viu um problema nesta lição? Reporte-o · Pergunte sobre esta lição

Este exercício abre em breve

Termine a lição anterior para que esta seja desbloqueada. O curso inteiro é gratuito, não precisa de conta, e você pode ler esta lição agora mesmo.