Readme файл для android приложения
Недавние к этомуREADME.mdФайл довольно интересный. Я написал этот пост, чтобы помочь большему числу студентов, которые не знают, как писать файлы README.
Суффиксом файла README является md. md - это аббревиатура от уценки, которая является языком для редактирования блогов. Используемая для визуальных редакторов блогов (таких как блог CSDN, 囧), эта программная программа для редактирования блогов действительно впечатляет. Однако грамматика, поддерживаемая GitHub, модифицируется на основе стандартной грамматики уценки и называется Github Flavored Markdown, или сокращенно GFM. Это не GFW。
Файл README этого хранилища постоянно обновляется, и новые записи в блоге могут не обновляться. Прежде всего, я настоятельно рекомендую вам не использовать браузеры 360 или Sogou для посещения веб-сайта GitHub, вы обнаружите, что многие кнопки на веб-сайте в настоящее время недоступны. , Для доступа к GitHub рекомендуется использовать Firefox или Google Chrome.
Откройте проект на вашем GitHub, мы можем напрямую отредактировать ваш файл README онлайн, если у вас уже есть этот файл, щелкните его непосредственно в каталоге файлов, если у вас его еще нет, нажмите кнопку справа от названия проекта Чтобы добавить новый файл:
Затем вы открываете страницу редактирования, в левом верхнем углу области редактирования есть область для заполнения имени файла, обратите внимание на добавление суффикса.md
Если у вас уже есть этот файл и вы хотите отредактировать его еще раз, то после щелчка по файлу в папке с файлами вверху появится панель инструментовEdit
Затем прокрутите экран вниз, если это новый файл, будетCommit new fileКнопка не может быть нажата, если нет содержимого. Если это новое редактирование старого файла, то эта кнопка показывает Commit changes
// Кстати, если это браузер 360 или Sogou, эта кнопка никогда не будет нажата, 囧. ,
Код выбран по умолчанию, это наш режим редактирования. Нажмите «Просмотр», чтобы отобразить текущий эффект отображения в режиме реального времени.
Хорошо, теперь официально начать редактировать этот файл
Заголовок записывается в начале стандартного файла README, который называется заголовком 。
Добавьте знак равенства = ниже текста, и текст выше станет заголовком. Количество знаков равенства не ограничено, но оно должно быть больше 0. ,
Средний заголовок на один уровень ниже, чем большой, что означает, что он отображается меньше, чем большой заголовок.
Добавьте символ подчеркивания ниже текста, затем текст выше становится средним заголовком, и количество подчеркиваний не ограничено.
Кроме того, вы также обнаружите, что под большими и средними заголовками есть горизонтальная линия. Это верно, это результат отображения = и -.
Если вы введете только знак равенства =, но над ним нет текста, будет отображаться только прямая линия. Если в верхней части есть текст, но вы хотите отобразить только горизонтальную линию и не хотите, чтобы текст в верхней части отображался в заголовке, вам нужно добавить пустую строку между знаком равенства = и текстом.
Заполнение пустых строк: это очень распространенное использование. Если вы не хотите, чтобы два разных макета были смещены вместе, вам необходимо заполнить пустую строку между двумя макетами.
Если вы вводите только тире (знак минус), а над ним нет текста, то для отображения прямой линии необходимо написать более трех знаков минус. Однако, в отличие от эффекта отображения знака равенства, он отображается в виде пунктирной линии, а не сплошной линии. Та же функция, что и со знаком минус, - звездочка * и подчеркивание _. Эти же два символа должны быть написаны более трех, чтобы отобразить пунктирную горизонтальную линию.
Фактически, упомянутые выше заголовки и средние заголовки соответствуют первичному и вторичному заголовкам соответственно. То есть размер большого заголовка такой же, как заголовок первого уровня, а размер среднего заголовка такой же, как заголовок второго уровня.
Обычный текст
Текст, введенный напрямую, является обычным текстом. Следует отметить, что если вы хотите изменить строку, вы не можете напрямую использовать возврат каретки для изменения строки, вам нужно использовать <br> (или <br/>). Какой тег в HTML 。На самом деле, уценка поддерживает некоторые HTML-теги, вы можете попробовать.Конечно, если вы используете html для полной записи, он потеряет свое значение: в конце концов, уценка не предназначена специально для front-end, но если она дает только общие эффекты, она будет гораздо более краткой, чем html.
Это обычный текст,
Возврат каретки напрямую не переносится, <br>
Использовать \ <br>
Обратите внимание, что обратная косая черта \ добавляется перед третьей строкой. Цель состоит в том, чтобы добиться побега, как и в других языках, то есть <побег.
Эффект заключается в следующем:
Кроме того, для отображенияГиперссылкаЕсли это так, просто введите URL этой ссылки напрямую. Дисплей автоматически станет связываемой формой.
Маленький совет с пробелами
Пробел по умолчанию в начале текстовой строки будет проигнорирован, но что, если вы хотите использовать пробел для упорядочивания версии? Есть небольшая хитрость, то есть изменение метода ввода с полуширины на полную ширину.Однострочный текст
Используйте два символа табуляции для получения однострочного текста.
После Hacktoberfest в проектах с открытым исходным кодом появилось много новых правок. Только за октябрь было сделало более 400 000 запросов на включение кода. Это невероятно!
Я решил подробнее изучить проекты с большим количеством правок. У этих проектов есть кое-что общее: отличный readme.md-файл. Сомневаюсь, что можно внести так много правок без хорошего readme. Между качеством readme и количеством правок определенно есть связь!
Обратим внимание на несколько известны х проектов: React, Vue, freeCodeCamp, Sourcerer и Serverless. В каждом из этих проектов readme.md-файл идеально сочетает в себе документацию, общие сведения о проекте, часто задаваемые вопросы и инструкцию по внесению правок. В них наглядно показано, что это за проект, какая у него экосистема, какое вокруг него сложилось сообщество.
Любому сообществу вокруг open source проекта нужен файл, который упростил бы коммуникацию. Этот файл похож на руководство, в нем разработчики детально рассказывают о проекте. Тем не менее, что же такое файл readme.md?
Файл readme.md — это основа любого проекта с открытым исходным кодом. Он дает полное понимание того, куда движется проект. Он объясняет, что это за ПО и зачем оно нужно. В нем указаны предварительные условия, которые помогают новым участникам проекта быстрее включиться в работу.
Самое важное: в readme-файле сказано, как запустить это ПО с целью разработки. Также в readme обязательно должна быть инструкция по развертыванию ПО в среде эксплуатации.
Мы составляем резюме, развиваем свой профиль на GitHub, заводим личный сайт, чтобы люди обратили внимание на нашу работу. Такой же подход применим и к проектам с открытым исходным кодом. Readme.md — это резюме вашего ПО. Добавьте в него все, что поможет будущим участникам проекта лучше понять ваше ПО.
Самый разумный подход: сначала написать readme.md, а уже затем опубликовать проект. Так будет намного проще отвечать на вопросы и помогать новым участникам.
Заведите себе правило: любой проект должен начинаться с readme-файла. Обязательно добавьте его в корневой каталог вашего проекта, чтобы его было видно на GitHub.
К счастью, изобретать велосипед не придется. Существует несколько отличных шаблонов. Помните, что у readme.md должна быть логичная структура: этот файл должен быть простым и понятным, чтобы сразу после его прочтения можно было приступить к работе.
Взгляните на этот прекрасный шаблон от Билли Томпсона. Он поможет написать отличный readme в считанные минуты.
Название проекта
Один параграф, описывающий проект
Приступая к работе
Инструкция о том, как получить копию этого ПО и запустить его на локальном компьютере с целью разработки и тестирования. Подробную информацию о развертывании ПО в условиях эксплуатации см. в разделе «Развертывание».
Предварительные условия
Что нужно для установки ПО, инструкции по установке дополнительных компонентов.
Установка
End with an example of getting some data out of the system or using it for a little demo
Пошаговая инструкция, которая поможет войти в среду разработки.
В конце на примере объясните, как извлечь данные из системы.
Тестирование
Объясните как запустить автоматическое тестирование этой системы.
Сквозное тестирование
Объясните, что проверяют эти тесты и зачем они нужны.
Тестирование стандартов оформления кода
Объясните, что проверяют эти тесты и зачем они нужны.
Развертывание
Более подробно расскажите, как развертывать ПО в условиях эксплуатации
Создано с помощью
-
— Платформа для разработки приложений — Управление зависимостями —Генерация RSS-лент
Внесение правок
Прочтите CONTRIBUTING.md, чтобы получить подробную информацию о правилах и процессе подачи запросов на включение кода.
Управление версиями
Для управления версиями мы используем SemVer. Информацию о доступных версиях см. в тегах в этом репозитории.
Авторы
- Билли Томпсон — Начальный этап работы — PurpleBooth
См. список тех, кто вносил правки в проект.
Лицензия
Этот проект лицензируется в соответствии с лицензией MIT — подробности см. в файле LICENSE.md.
Благодарности
- Благодарность тем, чей код был использован в проекте
- Благодарности за вдохновение и мотивацию
- и т.д.
Есть несколько моментов, которые нужно упомянуть. Прежде всего, этому шаблону не хватает взаимодействия с сообществом. Не стесняйтесь добавлять изображения, значки, изображения, видео и даже GIF в ваши readme.md-файлы. Не забывайте, что ваша цель — сделать так, чтобы ваш проект понравился людям. Отдельную благодарность нужно выразить тем, кто помогал и вносил правки.
Помните, что вам нужно привлечь внимание сообщества и поблагодарить тех, кто вносит правки. Используете значки, чтобы показать статус сборки, полноту тестирования, PR-статус, наличие уязвимостей, лицензию. Экспериментируйте с ними, так ваш проект будет выглядеть серьезнее. Одобрение других людей — это самый важный показатель в сообществе разработчиков ПО с открытым исходным кодом. Скопируйте приведенные ниже значки или сделайте их сами. 😉
Еще один потрясающий инструмент, с помощью которого можно добавить наглядности и поблагодарить тех, кто вносит правки — это Hall of Fame.
Упоминание людей, которые участвуют в разработке — важный шаг, который помогает привлечь внимание сообщества. Мне кажется, каждому хочется получить признание от известного проекта с открытым исходным кодом.
Если ваш проект начнет стремительно расти, стоит задуматься о создании Contributing.md, в котором вы расскажете о том, как подавать запросы на включение кода. Этот файл станет официальным руководством для тех, кто захочет внести вклад в ваш проект.
Не останавливайтесь на достигнутом. Во-первых, добавьте license.md, чтобы подробнее рассказать, насколько открыт ваш код. Затем напишите code_of_conduct.md, чтобы объяснить общие правила работы для разработчиков: этот «свод правил поведения» необходим для комфортной работы друг с другом.
У всех успешных проектов с открытым исходным кодом readme.md сделан очень качественно, и это не случайность. Внимание людей ограничено. Хороший readme.md помогает привлечь разработчиков, которые будут вносить вклад в проект. Глядя на freeCodeCamp и Sourcerer, можно увидеть много общего: в их 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, я советую воспользоваться следующими источниками:
Эта статья является продолжением. Первую часть смотри тут
Подход к реализации
Файл 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.
Читайте также: