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.
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.
Este navegador está bloqueando cookies para learn.floati.life, então as lições que você terminou aqui não podem abrir em ordem. Permita cookies para este site e recarregue.