Файл readme что это
Перевод статьи «How to write a kickass README».
Вероятно, README это самая простая часть документации любого проекта с открытым исходным кодом. Хороший README сообщает людям не только о том, что делает проект и для кого он предназначен, но и о том, как именно нужно использовать проект и как принять участие в его разработке.
Если не уделить должного внимания составлению хорошего README, где объяснялось бы, как пользоваться проектом и для чего он вообще создан, такой проект не оправдает себя в качестве именно open source проекта, поскольку другие разработчики с меньшей вероятностью станут в нем участвовать.
Что такое README?
По сути, README это просто текстовый файл (в формате .txt или .md), играющий роль быстрой справки по проекту или директории. Обычно это самая заметная часть документации и landing page для большинства проектов с открытым кодом. Даже само название файла пишется одними заглавными буквами, чтобы привлечь внимание читателя и побудить его прочесть это файл в первую очередь.
Доказано, что файлы README появились уже в 1970-е. Самый старый найденный мной экземпляр README датируется 27 ноября 1974 года (создан для DEC компьютера PDP-10). Есть много версий, почему файл первичной документации принято называть именно README, но основных среди них две:
- Программисты мэйнфреймвов, работавшие с перфокартами, оставляли стопку инструкций (в бумажном виде) на передней панели и помечали их надписью «READ ME!» («Прочти меня!»).
- Название является отсылкой к «Алисе в стране чудес» Льюиса Кэрролла. Там Алиса находит пузырек с надписью «DRINK ME» («Выпей меня») и пирожное с надписью «EAT ME» («Съешь меня»). И то, и другое, позволяет ей меняться в размерах.
Что нужно включить в файл README?
Так что же должен содержать идеальный файл README? В качестве отправной точки я рекомендую воспользоваться следующим списком:
1. Название продукта
Не забудьте дать своему проекту имя. На GitHub просто на удивление много безымянных проектов.
2. Введение или краткое описание
Напишите две-три короткие строчки, поясняющие, что делает ваш проект и для кого он предназначен. Не вставляйте заголовки типа «Вступление», «Обзор» и т. п. — и так очевидно, что это введение.
3. Необходимые условия для использования продукта
Сразу после введения добавьте раздел, где будут перечислены все знания и инструменты, необходимые тому, кто пожелает воспользоваться вашим проектом. Например, если продукт запускается на последней версии Python, напишите, что нужно установить Python.
4. Как установить программу
Опишите шаги инсталляции! Просто поразительно, сколько есть проектов, где описано, как использовать продукт, но нет ни слова о том, как его установить. Вероятно, ожидается, что читатель волшебным образом сам догадается. Если процесс установки достаточно длинный (сложный), обязательно разбейте его на отдельные этапы и пронумеруйте их.
5. Порядок использования
Опишите, как пользователь может использовать ваш проект после установки. Обязательно включите примеры использования, ссылки на пояснение опций команд или флагов (если считаете, что это будет полезно). Если у вас есть более подробная документация в отдельном файле или на сайте, поставьте ссылку на нее.
6. Как принять участие в проекте
Опишите шаги, которые должен пройти потенциальный контрибьютор. Возможно, вы могли бы создать руководство в отдельном файле и поместить ссылку на него в README. Укажите в руководстве все, что вы хотите, чтобы люди знали, прежде чем отправлять пул-реквесты.
7. Добавьте список контрибьюторов
Укажите всех людей, которые участвовали в создании этого проекта. Это хороший способ сделать так, чтобы open source казался плодом командных усилий. Также таким образом вы поблагодарите всех людей, потративших время на участие в вашем проекте.
8. Добавьте раздел с благодарностями
Также, если вы использовали чью-то еще работу (код, дизайн, изображения и т. п.) и копирайт обязывает вас указать автора, вы можете сделать это , добавив специальный раздел. Тут можно поблагодарить и других разработчиков или даже целые организации, оказавшие помощь проекту.
9. Контактная информация
Возможно, вы замкнутый человек, избегающий любой публичности, и совершенно не хотите рассекречивать свои контакты. Но лучше все же их добавить где-нибудь на видном месте — на случай, если у людей возникнут вопросы по продукту, если кто-то захочет принять участие в разработке или — чем черт не шутит! — если кто-то так восхитится вашим проектом, что захочет предложить вам работу.
10. Информация о лицензии
Добавьте немного блеска
Если хотите, чтобы ваш README выделялся и имел привлекательный вид —
- Добавьте логотип. Если у вашего проекта есть лого, разместите его в верхней части README. Благодаря брендингу проект выглядит более профессиональным, кроме того, это помогает людям его запомнить.
- Добавьте значки или плашки. Они помогут вам быстро показать посетителям текущий статус проекта, лицензию, обновление зависимостей. Плюс, они просто круто выглядят! Можно воспользоваться готовыми значками или создать собственные на Shields.io.
- Добавьте скриншоты. Иногда простой скриншот или серия скриншотов бывают полезнее тысячи слов. Но будьте внимательны! Если вы используете скриншоты, следите за их актуальностью и обновляйте по мере обновления проекта.
- Используйте эмодзи(?). Сегодня во многих проектах используются эмодзи, но, конечно, только от вас зависит, хотите ли вы тоже их использовать. Это может быть хорошим способом добавить немного цвета и юмора в ваш README и слегка «очеловечить» проект.
Ресурсы
Если хотите узнать еще что-то о написании README, я советую воспользоваться следующими источниками:
Перевод статьи «Creating a Killer GitHub Profile README. Part 1».
README. Те самые файлы в markdown-разметке, которые вы создаете для нового проекта или GitHub-репозитория. Возможно, вы редактируете README для каждого своего проекта. А может, предпочитаете просто оставлять в этих файлах шаблонное содержимое.
Начиная с июля 2020 года GitHub дает возможность разработчикам создавать репозитории на уровне профиля и использовать README для персонализации их страниц.
Я знал об этом несколько месяцев, но лишь недавно решил углубиться в эту тему. Ну… возможно, я даже слишком углубился.
Многие разработчики, как мне кажется, зря вставляют в свои профили множество «крутых» виджетов и бейджей. Они делают это, не осознавая, что профиль на GitHub похож на портфолио. Он должен подчеркивать то, что делает вас уникальным.
В интернете есть много статей и руководств о том, как добавить в файл README.md самые базовые вещи: изображения, бейджи, статистику. Но я хотел получить что-то более личное, я хотел уникальный профиль. Он должен был:
Я советую вам составить собственный список того, что вы хотите видеть в своем профиле. Подумайте, как он должен отображать вашу уникальность.
В этой и следующей статье я опишу, шаг за шагом, как я оформил мой профиль. Возможно, это поможет вам создать собственный файл README.md, чтобы выделиться на общем фоне.
Разбираемся с ограничениями
Если для вас markdown-файлы это вообще нечто новое, вам нужно получить общее представление о том, что мы будем делать. В конце концов, без понимания ограничений никакое решение не сконструируешь.
Но я также знал, что мой README должен быть динамичным. Я хотел, чтобы он автоматически извлекал мои последние посты в блоге и отображал цитату из сериала при помощи созданного мной API. Вот это было уже сложнее. Markdown-файлы не умеют сами делать API-запросы. Как же добавлять динамический контент?
GitHub Actions. Эти встроенные конвейеры репозиториев позволяют разработчикам автоматизировать задачи и процессы. Вот их-то я и использовал для извлечения своих последних постов и отправки запроса на случайную цитату в мой API. Эти рабочие потоки могут триггерить файлы или функции для получения информации и вставлять контент в README.
Я настроил задачу cron для запуска процесса каждый час, так что мой профиль постоянно обновляется новыми статьями, а посетители при каждом заходе на мою страницу получают новую цитату.
В следующей статье я подробнее остановлюсь на реализации всего этого, но надеюсь, этот обзор дал вам представление о том, как вообще подходить к проблеме.
Создайте репозиторий вашего профиля
Я установил доступ к репозиторию как private, чтобы не показывать его людям, пока все не будет готово, но вы можете сразу сделать публичным, если хотите.
Также я сразу инициализировал репозиторий файлами README.md и .gitignore.
Примечание. На скриншоте вы видите полученную мной ошибку. Дело в том, что у меня уже был создан репозиторий уровня профиля. У вас такой ошибки не должно возникнуть. Также, если вы не знали, не так давно GitHub выкатил темный режим.
Создав репозиторий, я сразу его клонировал и открыл в своем любимом редакторе.
Создание шаблона README
Хотя я инициализировал репозиторий файлом README.md, я быстро обнаружил, что мне придется редактировать мой контент в отдельном файле и использовать его как шаблон. Этот шаблон будет скелетом из статического контента, который я использую для создания финального README.md. Для такого решения было несколько причин, но из них можно выделить две основные:
- По моей задумке рабочий поток GitHub Actions будет триггерить файлы, использующие этот шаблон, вставлять динамический контент, а затем брать весь шаблон и вставлять его в файл README.
- Если редактировать файл README.md напрямую, после вставки динамического контента получите множество конфликтов слияния.
Картинка-баннер
Я решил, что хочу приветствовать посетителей моего профиля красивым баннером. При клике он должен перенаправлять их на мое портфолио.
В репозитории я создал новую директорию на уровне корневой и назвал ее assets. Сюда я поместил только что созданный файл с баннером и использовал его в файле README.template.md.
Бейджи соцсетей
Поэтому я поместил бейджи соцсетей вверху профиля, чтобы посетители обращали на них внимание в первую очередь.
Для создания этих бейджей я воспользовался shields.io, отредактировав текст, цвет и URL назначения.
Я подумал, что также будет здорово отслеживать посещения моего профиля, поэтому создал специальный бейдж и поместил его рядом с бейджами соцсетей.
Чтобы создать собственный бейдж такого рода, скопируйте разметку «Visits Badge», приведенную ниже, и поменяйте в URL адрес репозитория (все после «/visits/»).
Вводный раздел
Теперь, когда посетители получили возможность увидеть мои социальные сети, нужно было дать им немного информации обо мне.
Для вступления я написал лишь маленькую аннотацию. Если люди захотят узнать обо мне больше, они смогут найти нужные сведения на моем сайте-портфолио или в профиле LinkedIn. Не совершайте ошибку и не перегружайте посетителей большим объемом информации.
В конце вступления я приглашаю посетителей посмотреть мой сайт-портфолио. Опять же, я даю людям лишь достаточную информацию обо мне и предоставляю способ узнать больше (при желании).
Последние посты из моего блога
В соответствии с моим планом, дальше посетители должны увидеть мои последние посты. Этот раздел должен быть динамичным и регулярно обновляться. Вся самая тяжелая работа в конечном счете будет делегирована в отдельный файл, запускаемый GitHub Action. Но чтобы этот файл знал, куда вставлять контент, нужен определенный паттерн в шаблоне.
Пока я поместил следующие строки в разделе постов из блога:
Закрепленные репозитории и GitHub-статистика
Навыки
Идем дальше. Мне нужен был способ рассказать посетителям о своих навыках full-stack веб-разработчика. Я не хотел просто перечислять их в маркированном списке: это заняло бы много места, к тому же список сложно сделать стильным.
Вместо этого я создал бейджи при помощи shield.io и отобразил их в ряд. Я использовал тот же цвет фона, что и для баннера, чтобы придерживаться постоянства в дизайне.
Поскольку я хотел перечислить много навыков, я решил основные отображать по умолчанию, а дополнительные выводить опционально, при помощи тега <details>.
Чтобы увидеть весь список бейджей, которые я использовал в файле README.template.md, кликните сюда.
Цитата из сериала «Офис»
Я хотел бы, чтобы перед уходом с моей страницы посетители увидели нечто уникальное, несущее мой персональный отпечаток. Поэтому GitHub Action будет, помимо вывода постов из блога, запускать еще один скрипт. Этот скрипт будет искать паттерн в README.template.md и вставлять случайно выбранную цитату.
В раздел Office quote я поместил следующий паттерн:
На этом работа со статическим контентом была завершена. Я достиг всех целей, которые ставил для своего профиля.
Многие программисты лихо управляются с кодом и знают мельчайшие подробности своих проектов. Но некоторым из них (в том числе и мне) недостаёт коммуникативных навыков.
Удивительное дело: программист может потратить час на подгонку внутренних и внешних отступов для одной-единственной кнопки и не найти каких-то 15 минут на файл Readme описания проекта.
Надеюсь, вы уже знаете, что такое файл readme.md и для чего он нужен.На всякий случай попробую объяснить.
Что такое Readme.md?
README (буквально означает «прочти меня») — это первый файл, который нужно читать, получив доступ к проекту на Github или любой Git-хостинговой площадке. Этот файл в первую очередь и предлагается вниманию пользователя, когда он открывает здесь репозиторий того или иного проекта. Такой файл содержит кучу полезной информации, так что его вполне можно рассматривать как справочное руководство по проекту.
Посмотрите, где у нас здесь файл Readme:
Файл Readme.md находится в корневой папке репозитория и автоматически отображается в каталоге проекта на github.
Расширение .md — это сокращение от слова markdown. Это язык разметки для форматирования текста. Его используют (как и язык разметки HTML) для нормального отображения документов.
Вот как выглядит файл разметки на github (здесь использован VSCode, который одновременно показывает нам файлы разметки и в режиме предварительного просмотра):
Здесь можно найти официальный гайд Github для формата разметки на тот случай, если вам захочется основательно разобраться в языке разметки.
Зачем тратить время на Readme?
Разъяснения закончены, теперь перейдём к делу. Итак, потратив несколько часов на проект, вы выкладываете его на GitHub в надежде, что кто-нибудь (коллеги, потенциальные работодатели или бывшая) его увидит. Вы правда думаете, что они станут заглядывать в root/src/app/main.js , чтобы оценить вашу прекрасную логику? Серьёзно?
Генерирование документации для ваших компонентов
Кроме readme проекта, для понятной кодовой базы необходимо документирование компонентов, благодаря которому упрощается сопровождение кода и повторное их (компонентов) использование. Для автоматического генерирования документации к компонентам, выкладываемым на bit.dev, можно использовать такие инструменты, как Bit (Github).
Создание краткого описания проекта
Для проекта надо подготовить хорошее описание. При составлении описания можно придерживаться такого плана:
Некоторые нюансы
Чтобы показать код разметки, используйте значок карандаша:
1. Добавляем картинки
У вас может быть отличная фотографическая память, но интересующимся вашим проектом могут понадобиться фотографии его демо-версии.
Так, в описание нашего образцового проекта «Паук» в readme добавлены такие изображения:
Кроме изображений, вы можете добавить и видео-описание проекта. Вот только Github не разрешает добавлять видео в readme… Что же делать?
Используем gif
2. Элементы оформления
Персонализированные или настраиваемые элементы оформления, такие как количество звёзд в репозитории и процентный индикатор кода, берутся там же.
3. Добавляем интерактивную демо-версию
Если есть возможность, разместите проект на своих ресурсах и установите запускаемую демо-версию. Затем пропишите в README ссылку на демо. Кто знает, сколько людей могут заинтересоваться вашим проектом и решить протестировать его? А уж работодатели просто обожают интерактивные проекты. Этим вы покажете, что ваш проект не просто кусок кода, лежащий на github, но заодно продемонстрируете своё серьёзное отношение к делу.
Да, всё верно: в readme можно использовать гиперссылки, так что поместите ссылку на интерактивную демо-версию прямо под изображением с названием.
4. Форматируем код
Разметка даёт возможность форматировать текст, как код. Поэтому не пишите код, как обычный текст, а воспользуйтесь знаком `, чтобы придать коду аккуратный вид var a = 1;
Github также даёт возможность указывать язык, на котором написан код, и использовать соответствующее выделение текста, улучшая читаемость кода. Вот как это делается:
5. Используем HTML
Да, внутри можно использовать HTML. Не все функции, но большинство. Рекомендуется всё же придерживаться разметки, но некоторые функции, такие как выравнивание текста и изображений по центру, в readme доступны только с использованием HTML.
6. Творим
Всё остальное зависит от вас. Ведь каждому проекту нужен свой readme и свой тип описания. Так проявите изобретательность: те 15–20 минут, которые вы потратите на readme, могут произвести неизгладимое впечатление на посетителей вашего профиля на github.
Эта статья является продолжением. Первую часть смотри тут
Подход к реализации
Файл Readme.md
- Название компонента
- Статус компонента (микросервиса) и его владелец
- Описание компонентов. Его назначение и связанная область данных
- Описание функциональности как набор реализованных сценариев использования.
- Инструкция по использованию, сборке и развертыванию
- Описание конфигурации
- Ссылки на документацию
- Важные советы и ссылки
Readme.md — Статус компонента (микросервиса)
В этой части должна содержаться информация о текущем состоянии компонента и его текущих версиях, находящихся в производстве или разработке. Статус показывает, что можно сделать с микросервисами в какой ветви.
Рекомендуемая структура статуса следующая:
- CREATED — микросервис создан, но в производстве нет версий. Пока не планируется запускать его в производство. Никаких ограничений не предусмотрено.
- DEV — разработка. Статус версии микросервисов, которая еще не запущена в производство, но будет выпущена. Каждый статус DEV должен указывать на соответствующую ветку. Статус DEV предполагает привязку к соответствующим ветвям выпуска. Таким образом, перед созданием новой ветки выпуска предполагается, что файл Readme.md в основной ветке должен быть обновлен новой веткой информации о выпуске.
- PROD- в производстве. Рабочая версия микросервисов. Каждый статус PROD должен указывать на соответствующую ветку. Таким образом, после нажатия в производственной конкретной ветке выпуска предполагается, что файл Readme.md в основной ветке должен быть обновлен с новым статусом выпуска. Кроме того, предыдущий выпуск может быть обновлен как статус EOL.
- EOL — конец жизни. Бетонный релиз снят с производства во всех средах.
- ARCHIVE- микросервис (как конкретное репо) удален из всех сред, и больше не предполагается подключение к нему задач разработки.
Readme.md — Владелец компонента
В этой части показано, кто является владельцем микросервиса и, следовательно, отвечает за его архитектуру и возможности. Обязанности собственника могут быть разными и зависеть от ситуации и текущей политики процесса развития
Readme.md — Описание компонентов
Описание компонента предполагает краткое объяснение, описывающее ваши микросервисы в терминах «О чем компонент?» и «Какова цель его использования?». Предполагается, что это описание того, какие общие сценарии использования решают микросервисы и какую область данных они обрабатывают.
В общем, это не должно превышать 30-50 строк текста, потому что это микросервис, а не типичное монолитное приложение.
Описание должно быть достаточно четким, чтобы предоставить всем разработчикам и архитекторам информацию, которая может им понадобиться для принятия решения — какие варианты использования целесообразно добавить в этот микросервис. Если по какой-либо причине в микросервис будет добавлен какой-то новый функционал, его описание необходимо расширить. В целом, это может быть хорошей точкой на этапе мерж запроса в качестве дополнительной точки архитектурного контроля.
Readme.md — Описание вариантов использования
Этот раздел должен содержать список всех вариантов использования, реализованных этим микросервисом. Предполагалось использовать уникальный номер варианта использования (который относится к используемому реестру вариантов использования) и имя варианта использования (не более одной строки текста).
На этапе слияния необходимо проверить, обновил ли разработчик часть вариантов использования в файле Readme.md в случае реализации нового варианта использования.
Readme.md — Инструкция по использованию, сборке и развертыванию
Этот раздел служит источником информации о том, как настроить, собрать и развернуть компонент. Самая важная часть — это описание всех файлов конфигурации и основных параметров конфигурации.
Предлагается иметь здесь единый список всех жизненно важных файлов конфигурации. Кроме того, все параметры конфигурации должны быть задокументированы в соответствующих файлах конфигурации с помощью комментария или java-doc.
В случае использования общего подхода к файлам конфигурации было бы лучше иметь ссылку на конкретную страницу Confluence с описанием общих параметров.
Приложения и инструменты, которые работают только на определенных платформах, должны иметь поддерживаемые версии операционной системы, указанные в этом разделе Readme.
Если ваш код полагается на другое приложение или библиотеку, обязательно укажите эти зависимости здесь.
Кроме того, это хорошее место для раздела часто задаваемых вопросов, который можно использовать для хранения полезных советов, которые обычно разработчики задают в чате разработки.
Readme.md — Ссылки на документацию
В этом разделе представлен набор ссылок на другую полезную документацию, которая может быть полезна для понимания того, как обрабатывать и использовать компонент (микросервис).
Предопределенная структура пакета кода
Во избежание ненужных зависимостей кода (и для упрощения документации) не должно быть прямых зависимостей между «inbound», «outbound» и «domain» пакетами. Только классы из бизнес-пакета могут напрямую использовать эти пакеты.
Кроме того, такое разделение классов сокращает необходимый объем документации по классам, и минимально необходимо документировать только только эти пакеты, так как они отвечают за межкомпонентное взаимодействие, о котором нельзя прочитать в коде -).
Аннотации Swagger для служб REST
Документирование службы REST для микросервисов — важная часть системной интеграции. Документация REST должна быть настолько полной, чтобы ее можно было использовать без необходимости чтения кода.
Аннотации Swagger должны содержать как минимум следующую информацию:
- Функциональная область
- Имя варианта использования, чтобы можно было легко найти исходные требования и тестовые примеры для конечного пользователя.
- определение ресурсов
- определения параметров
- определения заголовков
- область авторизации и необходимые роли безопасности, если это применимо
Модель документа Jira
Это отличный способ использовать журнал задач и проблем в качестве источника документации о микросервисе в контексте цели микросервиса, реализованной пользовательской истории и связанных архитектурных решений.
В общем, структура артефактов Jira может быть похожа на следующую диаграмму:
Все пользовательские истории — это Jira-issue, связанные с соответствующими issue проектирования, разработки или ошибок. Те, с другой стороны, подключены к определенному микросервису с помощью Component Object Jira. Таким образом, в результате мы можем достичь прочной связи между микросервисами, их функциональной документацией и библиотекой архитектуры решения.
Детали реализации могут быть разными, но основная идея будет той же — как с минимальными усилиями связать кучу документации из разных источников (например, в Confluence) с конкретной реализацией микросервиса.
Confluence может быть отличным местом для библиотеки документации, так что все проблемы, связанные с историей пользователей и решениями, должны быть связаны с соответствующей страницей документации в Confluence.
Swagger-HUB
Swagger-HUB в настоящее время широко используется и тут нет особого смысла описывать его имплементацию. Главное чтобы она была автоматизирована, включена в build-pipeline, предоставлялась также для релизных веток, а не только для продуктивной.
Заключение
Наличие актуальной документации очень важно для повышения качества системы и скорости разработки. С первой стороны, похоже, что разработчику, которого заставляют задокументировать свой код, придется снизить скорость разработки. Но, с другой стороны, существует необходимый минимум документации, без которой процесс разработки замедляется из-за большого количества времени, необходимого для доработок, рефакторинга и исправления ошибок.
Более того, отсутствие минимальной документации обеспечивает тесную связь разработчиков с их кодом. В результате у нас может быть в результате «несменяемая суперзвезда», что может стать реальной проблемой в процессе разработки.
Второй момент: лучше не иметь документации вообще, чем иметь неактуальную и устаревшую документацию. В некоторых случаях текущее состояние и актуальность SwaggerHub не соответствуют действительности, поэтому он бесполезен в качестве источника API.
Читайте также: