Руководства для проектов

Шаблон GitHub README для проекта с открытым исходным кодом

Полезный README на GitHub быстро отвечает на четыре вопроса: что делает проект, для кого он, как его попробовать и где получить помощь? Возьмите приведённый ниже шаблон Markdown за основу, а затем замените все заполнители сведениями, проверенными на вашем проекте.

Редакция GitHubStart · Обновлено

Скопируйте этот шаблон README в Markdown

Это подготовленный стартовый шаблон, а не работающий пример ПО. Замените текст в скобках, убедитесь в наличии указанных файлов и удалите ненужные разделы. Строки установки и запуска ниже оформлены как комментарии, чтобы команды-заполнители нельзя было случайно выполнить.

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

[Одно предложение: проблема, целевой пользователь и результат.]

## Пример
[Покажите небольшие входные данные и ожидаемый результат или добавьте снимок экрана.]

## Быстрый старт
Требования: [среда выполнения/версия и необходимые службы].

```sh
# Замените проверенной командой установки.
# Замените самой короткой командой, дающей полезный результат.
```

Ожидаемый результат: [что должен увидеть читатель].

## Настройка
[Обязательные параметры, безопасные примеры значений и место хранения секретов.]

## Когда использовать
- [Конкретный сценарий]
- [Второй сценарий]

## Ограничения
[Неподдерживаемые входные данные, зрелость, ограничения производительности или платформы.]

## Документация и помощь
[Ссылка на документацию и пояснение, где задать вопрос.]

## Участие в разработке
См. [CONTRIBUTING.md](CONTRIBUTING.md).
Сообщайте о воспроизводимых проблемах на вкладке Issues репозитория.

## Лицензия
См. [LICENSE](LICENSE).

Адаптируйте пример к типу репозитория

Для инструмента командной строки покажите входной файл, команду и краткий вывод. Для библиотеки приведите минимальный полный пример импорта и вызова, включая ожидаемое возвращаемое значение. Для веб-приложения покажите основной рабочий процесс и объясните, доступна ли размещённая демоверсия или локальная установка.

Не ограничивайте объяснение API снимком экрана: читатели должны иметь возможность скопировать код. Визуальному приложению, напротив, полезен снимок экрана с понятным описанием действий пользователя. Используйте реальные примеры из версии, которую вы сейчас распространяете.

  • Библиотека: установка, поддерживаемая среда выполнения и один полный вызов функции.
  • CLI: входные данные, команда, вывод и способ сообщения об ошибках.
  • Веб-приложение: ссылка на демоверсию или локальная установка, настройка и снимок экрана основной задачи.
  • Набор данных: происхождение, формат, лицензия и небольшой пример записи.

Проверьте README перед публикацией

Попробуйте быстрый старт в чистой среде, а не на компьютере, уже настроенном для разработки. Проверьте, не требуются ли неуказанный глобальный пакет, приватный реестр или локальный файл. Если настройка требует аккаунта или платного сервиса, сообщите об этом до первой команды.

Откройте ссылки на документацию и изображения со страницы репозитория. Убедитесь, что имена файлов с правилами участия и лицензией соответствуют репозиторию, и удалите неработающие ссылки. Короткий точный README лучше впечатляющего шаблона с обещаниями ещё не реализованных возможностей.

  • Удалите заполнители и неподтверждённые заявления.
  • Не включайте в примеры настоящие токены, пароли и приватные URL.
  • Проверьте, что ожидаемый вывод соответствует опубликованной версии.
  • Объясните читателям, какие сведения включать в сообщение о проблеме.

Используйте README как основу анонса

Завершив шаблон, выделите короткое представление: одно предложение о проблеме, один пример результата и одну ссылку для знакомства. Это станет основой публикации в сообществе. Сохраните исходный README как подробный источник, а каждое представление адаптируйте к читателям вместо повторения рекламного абзаца повсюду.

Частые вопросы

Это README репозитория или профиля?

Шаблон предназначен для репозитория ПО. README профиля представляет человека и требует других разделов, например о его работе и предпочтительных способах связи.

Стоит ли добавлять значки звёзд вверху?

Только если они помогают читателю. Назначение проекта и быстрый старт должны быть заметны. Значок не заменяет объяснения того, что делает проект.

Можно ли использовать шаблон для приватного проекта?

Да. Замените публичные ссылки поддержки реальными каналами помощи вашей команды, объясните требования доступа и не включайте учётные данные в документ.

Источники