README

README — файл в корне репозитория с описанием проекта. GitHub/GitLab/Bitbucket рендерят его на странице репо. Первое что видит человек — README. Плохой README = мёртвый проект.

Форматы

Приоритет GitHub: .md > .rst > без расширения.

Классические разделы

# Название проекта

Одна строка описания.

## Установка
## Использование / Quick start
## Примеры
## Настройка
## API / Документация
## Разработка
## Тестирование
## Вклад / Contributing
## Лицензия

README-driven development

Идея Tom Preston-Werner (co-founder GitHub): сначала пиши README, потом код. Заставляет продумать API до реализации.

If the readme is the last thing to be written, the project is doomed.Tom Preston-Werner

Badges (shields.io)

![Build](https://github.com/user/repo/workflows/CI/badge.svg)
![npm](https://img.shields.io/npm/v/package)
![License](https://img.shields.io/github/license/user/repo)
![Downloads](https://img.shields.io/npm/dm/package)

Первые 5 строк

1. Название проекта
2. Одно предложение что это
3. Кому и зачем
4. Screenshot/GIF если UI
5. Quick start (3-5 копипаст-команд)

Anti-patterns

• Только npm install без примера использования
• TODO/WIP на 90%
• Скриншот вместо кода команд
• Только ссылка на "документацию"

Спец-README на GitHub

• Profile README — репо с именем твоего юзера, показывается на профиле
• Organization README — репо .github, для orgs

Генераторы

• readme.so
• shields.io
• makeareadme.com
• awesome-readme

Про кефевеле

Список всех страниц сайта → /all. README-файл репо — на сервере, /var/www/kefewele/README.md.

См. также

• все страницы, GitHub, GitLab