Создание README для репозитория

  • Статья

Azure DevOps Services | Azure DevOps Server 2022 — Azure DevOps Server 2019

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

  • Пользователи, которые просто хотят запустить код.
  • Разработчики, которые хотят создать и протестировать код. Разработчики также являются пользователями.
  • Участники, которые хотят отправить изменения в код. Участники — это разработчики и пользователи.

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

Ниже приведены некоторые отличные средства чтения, которые используют этот формат и говорят всем трем аудиториям, для справки и вдохновения:

Создание интро

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

Помогите пользователям приступить к работе

Руководство пользователей по получению и запуску кода в собственной системе в следующем разделе readme. Будьте сосредоточены на основных шагах, чтобы приступить к работе с кодом. Ссылка на необходимые версии любого необходимого программного обеспечения, чтобы пользователи могли легко получить к ним доступ. Если у вас есть сложные действия по настройке, задокументируйте их за пределами readme и свяжите их.

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

Предоставление действий по сборке для разработчиков

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

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

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

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

Помогите пользователям внести свой вклад

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

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