Cartesian School CartesianSchool
Python с нуля / Глава 23 / README
Глава 23 · Часть III · Создаём Python-проект

Первый README проекта

README отвечает на вопросы «что это?» и «как запустить?» ещё до того, как человек откроет код.

SafeSort · Часть 3 из 6Проект
safesort/
.git/
README.mdНОВОЕ
README.md — один из файлов стартового коммита, увиденного в предыдущем разделе.

README — первый файл, который видит человек, открывший репозиторий: GitHub автоматически показывает его содержимое на главной странице проекта. В клонированном репозитории README.md уже существует и уже закоммичен — это часть стартового коммита chore: initial project scaffold, который был показан в предыдущем разделе. Сейчас он совсем короткий:

README.md
# SafeSort

SafeSort — программа для безопасной сортировки файлов по папкам.

Раз файл уже отслеживается Git, git status в чистом рабочем дереве ничего не покажет — нечего добавлять и нечего коммитить. Интересное начнётся, когда в файл внесут изменения: именно так README и растёт по ходу главы — дополняется разделами, а не переписывается с нуля. Добавим первый такой раздел:

README.md
# SafeSort

SafeSort — программа для безопасной сортировки файлов по папкам.

## Установка

pip install -e .
~/safesort $ git diff
diff --git a/README.md b/README.md
index f5a2610..d60da39 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,7 @@
# SafeSort
SafeSort — программа для безопасной сортировки файлов по папкам.
+
+## Установка
+
+pip install -e .
~/safesort $ git status
M README.md

git diff показывает построчную разницу перед коммитом, git status — что именно изменилось с последнего коммита. По мере того как в проекте появляются установка, команды и тесты, в README добавятся такие же короткие разделы Usage и Tests. Полный README проекта, уже дополненный: projects/python/safesort/README.md.

Без придуманных значков
На странице проекта на GitHub иногда встречаются цветные значки (badge) вида «tests: passing». Такой значок честен только тогда, когда его действительно обслуживает настроенная проверка — мы вернёмся к этому, когда подключим GitHub Actions. Вставлять его раньше значит показывать то, чего на самом деле ещё нет.

Коротко

  • README.md — первое, что видит человек, открывший репозиторий на GitHub.
  • README можно дополнять по мере роста проекта, а не писать целиком с первого раза.
  • git diff показывает построчные изменения, git status — какие файлы затронуты.
← Назад
Репозиторий проекта