Документация по управление версиями

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

Синтаксис управления версиями позволяет читателю вручную выбрать версию документации, которая применяется к используемому продукту. Url-адреса GitHub Docs' также могут включать сведения о версиях, что позволяет ссылкам из одной версии GitHub Docs в другую отправлять читателя непосредственно в документацию для используемого продукта.

How and where to version

Управление версиями для содержимого на GitHub Docs является одним источником, чтобы избежать повторения и сохранения prose DRY. В статьях вы применяете управление версиями к отдельному файлу Markdown с метаданными YAML, а затем используйте условные инструкции в прозе файла, чтобы указать сайту, какой текст будет отображаться в зависимости от версии, которую выбирает читатель. Одинарный источник контрастирует с созданием отдельных файлов, которые отражают каждую версию содержимого.

Существует два типа синтаксиса управления версиями для GitHub Docs.

• YAML: чаще всего используется в интерфейсе YAML в файлах content/Markdown, но и во многих типах файлов YAML в data/. Указывает управление версиями для всего содержимого.

  versions:
    PRODUCT: 'VERSIONS'
    PRODUCT: 'VERSIONS'
    ...
  

  В следующем примере показаны версии содержимого для Free, Pro, Team и все версии GitHub Enterprise Server.

  versions:
    fpt: *
    ghes: *
  

• Liquid: используется в файлах Markdown и content/ data/reusables/, переменных строк в файлах YAML в data/variables/или строках внутри data/glossaries/external.yml. Указывает, какой текст должен отображаться, когда средство чтения выбирает версию для содержимого с несколькими версиями, определенными интерфейсом YAML.

  • Управление версиями на основе продукта:

    {% ifversion SHORT-PRODUCT-NAME %} ... {% endif %}
    

  • Управление версиями на основе функций:

    {% ifversion FEATURE-NAME %} ... {% endif %}
    

О различных версиях GitHub

Мы предоставляем версию документации для пользователей планов GitHub, включая GitHub Enterprise Cloud и GitHub Enterprise Server. Если на сайте существует несколько версий страницы, читатели могут выбрать версию из средства выбора версий в верхней части страницы.

GitHub.com

В документации по GitHub.com есть две возможные версии:

Бесплатные, профессиональные или тарифный план команды

Для бесплатных, pro или тарифный план команды на GitHub.com, используйте free-pro-team@latest. Короткое имя fpt.

GitHub Enterprise Cloud

Для GitHub Enterprise Cloudиспользуйте enterprise-cloud@latest. Короткое имя ghec.

GitHub Enterprise Server

Документация по GitHub Enterprise Server имеет несколько версий и может быть разделена на два типа: документация по поддерживаемым выпускам (мы поддерживаем четыре в любое время) и документация для выпусков устарел (мы не ссылаемся на них на сайте документации, но мы поддерживаем "замороженный" моментальный снимок этих документов в постоянности, чтобы они по-прежнему могли быть доступны, если вы знаете URL-адреса). См lib/enterprise-server-releases.js . список.

Именуются enterprise-server@<release>версии. Короткое имя ghes. В условных выражениях Liquid можно указать диапазоны, например ghes > 3.0. Дополнительные сведения см. в разделе "Управление версиями с помощью условных операторов Liquid".

Управление версиями в интерфейсном элементе YAML

Свойство можно использовать versions в интерфейсном элементе файла для определения продуктов, для которых будет отображаться статья. Для файлов индексов требуется versions свойство, но они будут автоматически версиями на основе версий своих дочерних элементов.

Например, следующий интерфейс YAML версии статьи для GitHub Enterprise Server 2.20 и выше и Free, Pro или Team.

title: About your personal dashboard
versions:
  fpt: '*'
  ghes: '>=2.20'

В следующем примере будет версия статьи для всех поддерживаемых версий GitHub Enterprise Server:

title: Downloading your license
versions:
  ghes: '*'

Вы также можете использовать страницу для диапазона выпусков. Следующий пример версии страницы для free, Pro и Team, GitHub Enterprise Cloud, а также GitHub Enterprise Server версии 3.1 и 3.2:

versions:
  fpt: '*'
  ghec: '*'
  ghes: '>=3.1 <3.3'

Управление версиями с помощью условных операторов Liquid

Мы используем язык шаблона Liquid (в частности, этот порт Node.js) и пользовательский {% ifversion ... %} тег для создания версий нашей документации.

Если вы определяете несколько продуктов в ключе в versions интерфейсном шаблоне YAML страницы, вы можете использовать условные операторы ifversion``else/(илиifversion//elsif``else) в Markdown для управления отображением содержимого сайта на странице для определенного продукта. Например, функция может иметь дополнительные параметры для GitHub.com, чем в GitHub Enterprise Server, чтобы можно было версию содержимого соответствующим образом с помощью versions frontmatter и использовать условные условия Liquid для описания дополнительных параметров для GitHub.com.

Операторы сравнения

Для версий, которые не имеют нумерованных выпусков (например fpt , и ghec), у вас есть два варианта:

• {% ifversion ghec %}
• {% ifversion not ghec %}

Для версий, имеющих нумерованные выпуски (только ghesв настоящее время), можно сделать то же самое для содержимого, доступного во всех выпусках или недоступных в любом из выпусков:

• {% ifversion ghes %}
• {% ifversion not ghes %}

Если необходимо указать содержимое, доступное только (или недоступное) в определенных выпусках, можно использовать следующие операторы:

Оператор	Значение	Пример
=	Равно	{% ifversion ghes = 3.0 %}
>	Более новые, чем	{% ifversion ghes > 3.0 %}
<	Срок давности	{% ifversion ghes < 3.0 %}
!=	Не равно	{% ifversion ghes != 3.0 %} (не используйте not в диапазонах)

Операторы ==``>=Liquid и <= не поддерживаются в GitHub Docs.

Логические операторы

Если все операнды должны иметь значение true для условия, используйте оператор and:

{% ifversion ghes > 2.21 and ghes < 3.1 %}

Если по крайней мере один операнд должен иметь значение true для условия, используйте оператор or:

{% ifversion fpt or ghes > 2.21 %}

Не используйте операторы && или ||. Liquid не распознает их, и содержимое не будет отображаться в предполагаемых версиях.

Элемент управления пробелами

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

Вы можете добавить дефис (-) в левой, правой или обеих сторонах, чтобы указать, что нет новой линии или другого пробела на этой стороне.

{%- ifversion fpt %}

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

1. This step is for all versions{% ifversion ghes %}
1. This step is for GHES only{% endif %}
1. This step is for all versions

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

1. This step is for all versions
{%- ifversion ghes %}
1. This step is for GHES only
{%- endif %}
1. This row is for all versions

Сведения об использовании версий на основе функций

При документе новых изменений или компонентов используйте управление версиями на основе функций.

Небольшое меньшинство признаков и изменений будет применяться только к одному продукту. Большинство функций приходят к GitHub.com и в конечном итоге достигают всех продуктов. Как правило, изменяется "поток" с GitHub.com (включая GitHub Enterprise Cloud) на GitHub Enterprise Server.

Управление версиями на основе компонентов предоставляет именованные флаги компонентов, упрощающие обслуживание и управление версиями документации. Вы можете использовать одно имя функции (или флаг) для группировки и версии prose на протяжении всего содержимого. Когда функция приходит к дополнительным продуктам, необходимо внести изменения только в управление версиями YAML в файле в пределах data/features/файла.

Управление функциями

Каждая функция управляется с помощью отдельных файлов YAML в data/features/.

Чтобы создать новую функцию, сначала создайте файл YAML с именем компонента, который вы хотите использовать в этом каталоге. Для функции с именем meow, будет использоваться значение data/features/meow.yml.

versions Добавьте блок в ФАЙЛ YAML с короткими именами версий, в которые доступна функция. Например:

versions:
  fpt: '*'
  ghec: '*'
  ghes: '>3.1'

Формат и допустимые значения совпадают с форматом и значениями свойства версий титульного листа. Дополнительные сведения см. в разделе "Версии" в репозитории github/docs README.

Условные выражения Liquid

Теперь можно использовать {% ifversion meow %} ... {% endif %} в файлах содержимого!

Frontmatter

Эту функцию можно также использовать в Frontmatter в файлов содержимого:

versions:
  feature: 'meow'

Вы можете использовать только одну feature запись в разделе versions, а значение feature может содержать только одно имя функции.

Вы можете объединить управление версиями на основе функций и стандартное управление версиями в интерфейсном режиме. При этом статья будет включена в супермножество всех версий, указанных в файле управления версиями на основе компонентов, и непосредственно в файле Markdown. Например, у вас может быть функция, которая в настоящее время доступна только в GHEC, и это указано в версии на основе функций. Тем не менее, вы хотите, чтобы эта функция была также видна в документации по FPT. В этом случае можно добавить fpt и feature в versions блок в переднем вопросе:

versions:
  fpt: '*'
  feature: 'some-new-feature'

Рекомендации

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

Избегайте ненужного управления версиями

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

• Спросите себя: "Могу ли я написать это содержимое таким образом, что применяется ко всем продуктам без каких-либо версий?"
• Попробуйте избежать снимка экрана управления версиями, если это возможно, учитывая необходимые усилия для их создания. Незначительные различия между копированием пользовательского интерфейса могут не повлиять на понимание. Если существуют текст или элементы пользовательского интерфейса для конкретного продукта, но снимок экрана по-прежнему предоставляет полезный контекст, спросите себя, влияет ли управление версиями на снимки экрана на значимую степень.
• Не давайте прозе версии, если вы можете объяснить концепцию или пройти читатель по процедуре без управления версиями для определенных продуктов.

При изменении существующего файла содержимого просмотрите существующую версию ранних и часто

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

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

Избегайте повторения как можно больше

Используйте синтаксис управления версиями в предложении или абзаце для разных планов или продуктов. Участник может изменять только один абзац с инструкциями управления версиями, а не рассматривать более крупные блоки версии текста и изменять аналогичные, но по-разному версии прозу в двух местах. Рецензент может предложить изменение один раз, а не оставить одно и то же предложение в нескольких местах. Но если поведение резко отличается или версия в предложении или абзаце становится сложным или трудным для участника синтаксического анализа, рассмотрите возможность повторения себя, чтобы сделать проза проще поддерживать.

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

  Вы можете сделать {% ifversion fpt %}что-то{% elsif ghec %}что-то другое{% endif %}.

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

  {% ifversion fpt %}

  Если вы используете бесплатную, pro или тарифный план команды, вы можете сделать что-то. Дополнительные сведения о том, что вы можете сделать с помощью бесплатной, pro или тарифный план команды...

  {% elsif ghec %}

  Если вы используете GitHub Enterprise Cloud, вы можете сделать что-то еще. Дополнительные сведения о том, что можно сделать с помощью GitHub Enterprise Cloud...

  {% endif %}

Быть явным, а не неявным

Если вы точно знаете, какие продукты описывают содержимое, версия явно для этих продуктов. Синтаксис, например not, и else , в частности, может быть непреднамерен. Конечный результат not и else зависит от основных вопросов каждой статьи, поэтому участник должен сделать больше исследований, чтобы понять прозе с этой версией. Это создает потенциал для ошибок. Сложность неявного управления версиями увеличивается в многократно используемых статьях, где статьи, ссылающиеся на повторное использование, могут иметь разные версии и, следовательно, различные оценки not или else. Мы также иногда представляем новую версию GitHub Docs, когда GitHub представляет новый продукт, который изменяет конечный результат not и else при добавлении новой версии в существующие статьи.

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

Проверка и взаимодействие с версиями при разработке и создании содержимого

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

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

Тестирование, тестирование и тестирование снова

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