Как написать общую спецификацию README

внешний интерфейс GitHub открытый источник продукт

задний план

Когда мы обычно разрабатываем проекты, мы обычно загружаем код на платформу размещения кода, чтобы упростить управление и обслуживание. В настоящее время наиболее используемой платформой для хостинга является Github, и есть несколько хорошо известных платформ для размещения кода в стране и за рубежом, таких как Gitlab, BitBucket, Code Cloud и Code Market.

Однако самая неприятная проблема, с которой мы часто сталкиваемся при совместной разработке нескольких человек, заключается в том, что, когда другие разработчики передают нам проект, они лишь кратко описывают существующие функции проекта.Я обнаружил, что даже самые основные проекты не были объяснены. В то время мимо скакали 10 000 лошадей, и я мог только проверять скрипты package.json, да и сам это понимал.

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


Что нужно для канонического README

Давайте взглянем на простую спецификацию README со скриншотом:

image1

Приведенный выше шаблон спецификации readme доступен в нашемfeflowизСпецификация READMEможно увидеть в


Итак, давайте вместе обсудим, что должна содержать полная спецификация README?

1. 项目描述
2. 如何运行
3. 业务介绍
4. 项目备注

Что делает каждый?

  • Описание Проекта

    Нам нужно объяснить название нашего проекта, краткое описание функций проекта, адрес склада кода и первое лицо, ответственное за проект. Тот, кто передает нам проект, является первым лицом, ответственным за проект.

  • как бежать

    1. Конфигурация среды разработки. Как правило, некоторые конфигурации рабочей среды нам нужны.
    2. Команды разработки и выпуска. Как мы начинаем локальную разработку с помощью команд, а также собираем и публикуем.
    3. конфигурация прокси. Если нашему проекту необходимо использовать некоторые прокси-инструменты при локальной разработке, такие как fiddler или whistle, нам нужно перечислить элементы конфигурации прокси. Лучше всего напрямую экспортировать файл конфигурации прокси и поместить его в проект
    4. выпуск. Если мы используем некоторые издательские платформы, лучше всего вставить модуль выпуска проекта и порядок выпуска, чтобы сократить временные затраты на выпуск нашего выпуска.
    5. Предупреждение об ошибках и мониторинг. Я считаю, что мы обычно развертываем службы оповещения об ошибках и службы журнала мониторинга для онлайн-проектов, чтобы мы могли своевременно устранять существующие проблемы с сетью.Здесь мы можем добавить некоторые идентификаторы атрибутов мониторинга проекта.
    6. API интерфейса. Здесь нам нужно вставить адрес и описание фонового интерфейса, извлеченного из проекта, а также нашего лидера интерфейса.Когда фоновая служба ненормальна, мы можем напрямую связаться с фоновыми студентами.
    7. отчетность данных. Мы добавили в наши обычные проекты некоторые отчеты по данным, которые используются для статистических бизнес-данных для студентов, изучающих продукт. Здесь мы лучше объясним, какие данные сообщаются. Если в рапорте будет проблема и придет девушка с товаром, мы не запутаемся.
  • Введение в бизнес

    Для внешнего интерфейса наш проект может иметь более одной страницы, тогда нам нужно предоставить следующую информацию:

    1. Адрес входа в бизнес и ссылка на каналТо есть входная страница всего нашего проекта, либо адрес более важной страницы. Для общих страниц входа мы можем использовать несколько каналов, поэтому нам нужно перечислить все ссылки на каналы.

    2. Страницы и описанияПеречислите всю информацию о странице в нашем проекте, например следующую:

      каталог страниц описание страницы ссылка на страницу Параметр Описание
      index титульная страница now.qq.com никто
  • Замечания по проекту В рамках проекта другим разработчикам необходимо сообщить некоторую ключевую информацию, такую ​​как упаковка и структура нашей страницы, на какие проблемы следует обратить внимание и т. д. Хотя эта информация не является обязательной, она может помочь другим разработчикам снизить риск. стоимость разработки.

Наконец

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


Технологический еженедельник IVWEBШок в сети, обратите внимание на публичный номер: сообщество IVWEB, регулярно публикуйте качественные статьи каждую неделю.

  • Сборник статей еженедельника:weekly
  • Командные проекты с открытым исходным кодом:Feflow