README + Запуск одной командой
У вас есть чистая структура и реальные тесты. Последний этап это то, что рецензенты проверяют в первую очередь: README и одна команда для запуска. Проект, который требует десяти минут догадок для запуска, кажется сломанным даже если он работает. Проект, который можно клонировать и запустить одной строкой, кажется профессиональным даже если он маленький. Тот же код -> совершенно разное впечатление.
README - это контракт. Читатель просматривает его сверху вниз и ожидает предсказуемой структуры: название проекта как заголовок, затем как его установить, затем как использовать, затем как протестировать. Конкретно, хороший README имеет заголовок верхнего уровня (# Something), затем эти разделы в таком порядке:
# 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
Порядок важен, потому что читатель следует ему как шаги. Использование перед Setup запутывает -> вы не можете использовать то, что не установили. Поэтому вы пишете checker, validate_readme(text), который возвращает True только если появляется заголовок # , за которым следует ## Setup, затем ## Usage, затем ## Tests, каждый после предыдущего. Отсутствующий раздел или разделы не по порядку возвращают False. Трюк: пройдите по строкам один раз, ведите "курсор" того, где вы находитесь, и требуйте, чтобы каждый раздел появлялся в позиции после курсора.
Запуск одной командой. Обратите внимание, что ## Usage строка выше это одна команда. Это цель Makefile или цели justfile, такой как make run -> одна запоминающаяся команда, которая запускает проект, чтобы никому не пришлось помнить полный вызов. Напишите make_run(name), которая возвращает строку этой команды для проекта, например python -m triage (или make run). Она должна включать имя проекта, нормализованное так же, как и директория пакета, чтобы другой проект давал другую команду.
Два честных, не оцениваемых примечания для реального репозитория. Во-первых, секреты: cp .env.example .env шаг существует, потому что ваш реальный API ключ идет в .env, который вы добавляете в .gitignore и never commit. Вы коммитите только .env.example -> shape конфига с плейсхолдерами. Утечка ключа в публичный репозиторий это классическая ошибка проекта в портфолио. Во-вторых, deploying this: чтобы выложить его в сеть, вы бы написали небольшой Dockerfile (скопируйте репозиторий, pip install, установите команду запуска как entrypoint) и отправили в PaaS типа Render, Railway или Fly. Эта часть не может быть запущена или оценена в вашем браузере -> это вам делать при публикации. Нажмите Run чтобы проверить полный README и вывести команду запуска.
Напишите две детерминированные части хорошего README. validate_readme(text) возвращает True если появляется заголовок # верхнего уровня, затем ## Setup, затем ## Usage, затем ## Tests, каждый после предыдущего (отсутствующий раздел или разделы не по порядку -> False). make_run(name) возвращает строку запуска одной командой (например, python -m <pkg> или make run), которая включает имя проекта, нормализованное как директория пакета, так что другое имя дает другую команду.
Заметили проблему в этом уроке? Сообщите о ней · Спросить об этом уроке
Это упражнение откроется скоро
Закончи предыдущий урок, чтобы открылся этот. Весь курс бесплатный, аккаунт не нужен, и ты можешь прочитать этот урок прямо сейчас.
Этот браузер блокирует cookies для learn.floati.life, поэтому завершенные здесь уроки не могут открыться по порядку. Разрешите cookies для этого сайта и перезагрузите страницу.