Перейти к основному содержимому

README.md

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

Ключевые элементы файла README​

  1. Название проекта. Четко укажите название вашего проекта в верхней части README.
  2. Инструкции по установке. Следует включить инструкции по установке зависимостей или конфигурации.
  3. Структура проекта. Опишите структуру проекта, включая основные каталоги и файлы, используемые в нем.
  4. Работа с ветками. От какой ветки вести разработку, какие ветки используются для разработки новых функций, исправления ошибок и т.д.
  5. Деплой проекта. Опишите процесс деплоя проекта на сервер.
  6. Устранение неполадок и часто задаваемые вопросы. В этом разделе можно предоставить решения распространенных проблем и ответить на часто задаваемые вопросы.
  7. Документация и ссылки. Предоставьте ссылки на любую дополнительную документацию, API, dev/prod ссылки проекта или любые связанные ресурсы.
  8. Известные проблемы. Перечислите все известные проблемы или ограничения, связанные с текущей версией.

Как поддерживать README?​

Readme файл должен быть актуальным. Любые изменения в проекте должны отражаться в README. Это включает в себя добавление новых функций, изменение конфигураций и обновление инструкций.

Примеры README​

Плохой пример README:
# Проект

Проект для фронтенда.

## Использование

Проект нужен для работы с фронтендом.

## Установка

## Дефолтный Readme который подятнулся с Next/React
Хороший пример README:
# Название проекта

## Описание

Краткое описание проекта.

## Инструкции по установке

1. Клонируйте репозиторий.
2. Установите зависимости.
3. Запустите проект (если для запуска используются специфические комманды то следует их описать).

## Структура проекта

project/
│
├── src/ # Исходные файлы проекта
│ ├── components/ # Компоненты приложения
│ ├── styles/ # Стили приложения
│ └── services/ # Сервисы для работы с данными
│
├── public/ # Публичные файлы
│ ├── images # Изображения
│ └── icons # Иконки
│
├── README.md # Файл README
│
└── package.json # Файл зависимостей и настроек проекта

## Работа с ветками

Feature branches: создаются с **master** ветки для разработки новых функций. Мержатся в **develop** ветку (для тех кто только подключился к проекту - pull request в **develop** ветку), после всех проверок делаем pull request в **stage/master**.

## Деплой проекта

Автоматическое развертывание при коммите, настроенном в проекте, с помощью pipelines и bash-скрипта (файлы bitbucket-pipelines.yml и deploy.sh).

## Устранение неполадок и часто задаваемые вопросы

### Сбой при установке зависимостей

Если возникает ошибка при установке зависимостей, попробуйте выполнить следующие действия...

## Документация и ссылки

- Variables
- Имя переменной | Описание

- [Документация по API](https://api.example.com)
- [Dev URL](https://dev.example.com)
- [Prod URL](https://prod.example.com)

## Известные проблемы

- Сбой при загрузке изображений на странице "Галерея".
- Медленная загрузка страницы юзера.
- Дублирование данных при обновлении страницы.

Полезные ссылки​