Руководство по стилю

Подход GitHub Docs к стилю

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

События журнала аудита

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

• События журнала безопасности
• События журнала аудита для организации
• События журнала аудита для вашего предприятия

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

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

видны узлы

Оповещения подчеркивают информацию в статье, которая имеет особое значение и оправдывает поток информации.

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

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

Типы оповещений

Мы используем пять типов оповещений: примечание, совет, важное, предупреждение и осторожность.

Примечание.

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

Заметки особенно полезны для обмена скобками, которые не являются центральными для описанного процесса:

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

Например, Оценка оповещений от сканирования секретов использует примечание, чтобы уведомить пользователей, что метаданные для GitHub токенов в настоящее время находятся в Публичный предварительный просмотр.

Совет

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

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

Внимание

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

Предупреждение

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

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

Например, Сведения о центрах сертификации SSH содержит инструкции для командной строки и использует предупреждение для информирования пользователей о том, что после выдачи сертификатов нельзя отменить:

Внимание

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

Оповещения о предупреждении обычно необходимы только при описании процессов, происходящих вне GitHub интерфейса, например, в командной строке или через API.

Форматирование оповещений

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

Оповещения отрисовываются с помощью Markdown.

Примечание.

> [!NOTE]
> Keep this in mind.

Совет

> [!TIP]
> Here's a suggestion.

Предупреждение.

> [!WARNING]
> Be careful.

Внимание!

> [!CAUTION]
> Be extremely careful.

Синтаксис Liquid для оповещений по-прежнему поддерживается и может по-прежнему отображаться в старых статьях, но не следует использовать для новых оповещений.

Дополнительные сведения о форматировании оповещений см. в разделе "Оповещения" в Использование Markdown и Liquid в документах GitHub.

Вызов действия (CTA)

CTA — это ссылка или кнопка, предлагающая пользователям выполнить следующий шаг в своем пути. Он отправит пользователя в другое расположение.

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

При рассмотрении того, когда следует использовать CTA, задайте следующие вопросы:

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

Мы должны использовать только CTA, когда ответ на оба вопроса да.

Как CTA отличается от ссылки?

CTA — это явное направление для пользователя, чтобы выполнить немедленное действие, например "Попробовать Copilot бесплатно" или "Создать собственный репозиторий". CTA в нашей документации должен вести людей только к домену, GitHubпринадлежащему -.

Например, CTA в Настройка пробной версии GitHub Enterprise Cloud ссылает на страницу корпоративных продаж на GitHub.com.

Строительство CTA

Чтобы создать действительный CTA-URL с правильными параметрами, используйте скрипт CTA builder в вашем репозитории документации:

npm run cta-builder

Сценарий проведёт вас через интерактивный процесс:

• Выберите подходящий GitHub продукт (ref_product)
  • Используйте github по умолчанию, если ссылка не зависит от конкретной функции или продукта
• Выберите тип действия (ref_type)
• Укажите стиль форматирования (ref_style)
• По желанию выберите конкретный план (ref_plan)

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

Например, скрипт может генерировать URL, например:

https://github.com/account/enterprises/new?ref_product=ghec&ref_type=trial&ref_style=button&ref_plan=enterprise

Код

Блоки кода

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

В блоках кода:

• Укажите язык примера после первого забора кода. Список всех поддерживаемых языков см. в разделе

• Не используйте HTML для стиля или разметки блока кода.

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

  • Использование:git checkout -b BRANCH-NAME
  • Избегать:git checkout -b <branch-name>

• Не используйте командные строки, как $ и перед самой командой. Эти запросы позволяют читателям копировать и вставлять команду.

  • Если вы показываете команду и выходные данные команды, закомментируйте выходные данные в примере.

  • Используйте:

    command
    # output
    

  • Избегать:

    $ command
    output
    

• Если пример кода включает { или } должен отображаться, заключите этот раздел, {% raw %}{% endraw %} чтобы отключить обработку Liquid для этого раздела.

  • Используйте:

    GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
    

  • Избегать:

    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    

• Если в примере кода содержится содержимое, которое следует проанализировать, заключите этот раздел в <pre>``</pre> теги, чтобы проанализировать, а не избежать содержимого в разделе.

Команды

Используйте встроенные блоки кода для ссылки на короткие имена команд.

• Используется: чтобы проверить состояние запущенного кластера, используйте ghe-cluster-status команду.

Используйте блоки команд для более длительных или более сложных команд.

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

  ghe-cluster-maintenance -s
  

Не включайте такие командные строки, как $. Избегайте встроенных ссылок в именах команд.

Выходные данные

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

• Используйте:

  git lfs install
  # Git LFS initialized.
  

• Избегать:

  $ git lfs install
  > Git LFS initialized.
  

Примеры

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

• Используйте:

on:
  schedule:
    - cron:  "40 19 * * *"

• Избегать:

schedule:
  - cron:  "40 19 * * *"

Имена файлов и имена каталогов

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

• Используйте: в README.md файле добавьте сведения о репозитории.
• Используйте: в .github/workflows/ каталоге example-workflow.yml создайте файл.
• Избегайте: в каталоге github/workflows/ создайте example-workflow.yml файл.
• Избегайте удаления****файла example.js .

Indentation;

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

• Используйте:

    steps:
      - uses: actions/checkout@v6
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python }}

Чтобы повторно использовать отступы, см. раздел data/reusables/README.md.

Запланированные рабочие процессы

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

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

Акцент

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

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

Например:

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

Сообщения об ошибках

Когда вы включаете текст сообщения об ошибке продукта GitHub или интерфейса в статью, отформатируйте текст в соответствии с интерфейсом, в котором оно появляется.

• Если сообщение появляется в GitHubвеб-интерфейсе или в графическом клиентском приложении, например GitHub Desktop в , GitHub Mobileобращайтесь с ним как с другим текстом в интерфейсе. Дополнительные сведения см. в разделе "Текст пользовательского интерфейса".

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

Срок действия содержимого

Как правило, не документируйте содержимое, которое истекает. Любой, кто посещает GitHub Docs сайт, должен быть уверен, что информация точна и актуальна.

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

Сноски

Избегайте использования сносок по возможности. Вместо этого следует использовать оповещение или представить информацию другим способом. См. некоторые примеры альтернативных сносок из NICE.org.uk.

Если необходимо использовать сноски, используйте собственные сноски Markdown ([^1]). Маркеры сносок будут гиперссылки на ссылку на сноску, которая будет указана в нижней части страницы с обратной ссылкой на маркер.

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

          [^1]: Not to be confused with Davy Jones of The Monkees

          [^2]: Also humans

| | Mona | Ursula | Paul | Davy Jones[^1] |
|---|---|---|---|---|
|Favorite pastime| Shipping code | Tricking mermaids[^2] | Predicting sports | Haunting seafarers |
|Uses powers for good| Yes | No | Yes | No |
[^1]: Not to be confused with Davy Jones of The Monkees
[^2]: Also humans

Заголовки

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

Если статья содержит заголовки, заголовки должны начинаться с заголовка уровня H2. Заголовки уровня H3 и H4 можно использовать для дальнейшего упорядочения содержимого в связанных группах, но нельзя пропустить уровни заголовков. Между заголовком и подзаголовоком должно быть текстовое содержимое, например введение.

• Используйте:

  ## HEADER (H2)
  
  TEXT
  
  ### SUBHEADER (H3)
  
  TEXT
  
  #### SUBHEADER (H4)
  
  TEXT
  

• Избегать:

  ## HEADER (H2)
  
  #### SUBHEADER (H4)
  

Каждый заголовок на одном уровне на странице должен быть уникальным.

• Используйте:

  ## Examples  (H2)
  
  TEXT
  
  ### Prompts for writing code (H3)
  
  TEXT
  
  ### Prompts for writing tests (H3)
  
  TEXT
  

• Используйте:

  ## Prompts for writing code (H2)
  
  TEXT
  
  ### Example (H3)
  
  TEXT
  
  ## Prompts for writing tests (H2)
  
  TEXT
  
  ### Example (H3)
  
  TEXT
  

• Избегать:

  ## Example prompts (H2)
  
  TEXT
  
  ### Example (H3)
  
  TEXT
  
  ### Example (H3)
  
  TEXT
  

Изображения

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

Не используйте анимированные GIF-файлы в документах.

Альтернативный текст

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

• Выразить основную идею или смысл изображения, а не описывать его буквально.
• Используйте 40–150 символов.
• Заканчивается знаком препинания. Как правило, это должен быть период, если замещающий текст не описывает изображение текста, которое заканчивается другими знаками препинания, например вопросительный знак или восклицательный знак.
• Не начинайте с "Изображение..." или "Рисунок...". Средства чтения с экрана говорят это автоматически.
• Начните с типа рисунка: "Снимок экрана..." или "Схема, показывающая..."
• Следуйте стандарту языка, используемого для описания элементов пользовательского интерфейса в тексте статьи.
• Поместите названия с несколькими словами, например имена элементов меню, в двойные кавычки ("").
• Если область изображения визуально выделена, опишите, как. Это позволяет пользователям чтения с экрана понять и описать зрячего друга или коллегу, что следует искать на визуальном языке.

Замещающий текст для снимка экрана

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

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

Формат

Снимок экрана: показанный Product name + UI element . И UI element + state of the element/controlsего keyboard shortcut XYZ, очертываются темно-оранжевым цветом.

• Для Product name, используйте GitHub название продукта или функции, например «GitHub Actions» или «GitHub репозиторий», а не просто «GitHub».
• Используйте переменную для слова GitHub , как мы делаем при выполнении копирования: {% data variables.product.prodname_dotcom %}
• Описать элементы пользовательского интерфейса согласованно с письменной документацией.
• Будьте гибкими с порядком слов, если это необходимо для ясности.
  • Например, напишите «Скриншот меню отладки в Visual Studio Code...» вместо «Скриншот Visual Studio Code меню отладки...», чтобы избежать множества существительных подряд.

Примеры

Скриншот GitHub коммиттеров по таблице репозитория. Горизонтальный значок кебаба и кнопка "Скачать CSV-отчет" выделены темно-оранжевым цветом.

Скриншот опций файлов в GitHub репозитории. Кнопка со стрелкой, указывающей раскрывающееся меню с надписью "Код", описывается в темно-оранжевый цвет.

Замещающий текст для схем и графов

Объясните информацию, передаваемую на схеме или графе в тексте на странице.

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

Пример

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

Например, ознакомьтесь с описанием этой схемы в документации по действиям.

Замещающий текст для изображений интерфейсов командной строки

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

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

Имена файлов для изображений

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

• Использование:data-pack-purchase-button.png
• Избегать:purchase_button.png
• Избегать:purchase-button-for-admins.png

Снимки экрана

Дополнительные сведения о создании и изменении образов версий см. в статье "Создание и обновление снимков экрана".

Диаграммы

Дополнительные сведения о создании схем см. в разделе Создание схем для GitHub Docs.

Инклюзивный язык

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

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

Ресурсы о инклюзивном языке

Руководство по стилю Майкрософт предлагает ресурсы для обмена данными без предвзятости, терминами специальных возможностей и написанием для всех возможностей:

• Взаимодействие без предвзятости
• Написание всех возможностей
• Термины специальных возможностей

Дополнительные ресурсы для изучения инклюзивного и доступного языка и стиля:

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

Сочетания клавиш

Чтобы представить сочетания клавиш, следуйте руководству по стилю Майкрософт, за исключением следующих различий:

• Используйте HTML-тег <kbd> для каждого отдельного ключа.

  • Использование:<kbd>Command</kbd>+<kbd>B</kbd>
  • Избегать:Command+B

• Используйте полные слова вместо символов для клавиш модификатора Apple.

  • Использование:Command
  • Избегать:⌘

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

  • Использование:., ,и →.
  • Избегайте:Period, Commaи Right arrow.

Основные сведения об использовании

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

• Базовый синтаксис — показать ключи между + сочетаниями ключей без пробелов.

  • Используется:<kbd>Command</kbd>+<kbd>B</kbd>— отрисовка в виде +.
  • Избегайте: или которые отображаются в виде <kbd>Command</kbd> + <kbd>B</kbd><kbd>Command + B</kbd>B или + .

• Всегда прописные буквные клавиши для общих ссылок и сочетаний клавиш.

  • Использование:Command+B
  • Избегайте:Команда+b.

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

          **Примечание.** Windows и Linux имеют <kbd>сокращенное сочетание клавиш CTRL</kbd> , в то время как в Mac он написан в полном объеме: <kbd>управление</kbd>.
  

  • Для Windows и Linux:

    • Использование:CTRL, ALT.
    • Избегайте:управление

  • Для Mac:

    • Использование: команда, параметр, элемент управления.
    • Избегайте:Cmd, ✔, Opt, ⌥, CTRL, ⌃

• Не путайте сочетания клавиш с ключами в последовательности.

  • Команда+B указывает, что пользователь должен удерживать клавишу COMMAND и нажимать клавишу B .
  • G I указывает, что пользователь должен нажать клавишу G, а затем нажать клавишу I.

• При описании сочетания клавиш для нескольких операционных систем добавьте операционную систему в квадратные скобки после сочетания клавиш. Сначала опишите ярлык Mac, а затем Windows/Linux.

  • Используется: , представленный следующим образом:<kbd>Command</kbd>+<kbd>B</kbd> (Mac) or <kbd>Ctrl</kbd>+<kbd>B</kbd> (Windows/Linux)

          <kbd>Команда</kbd>+<kbd>B (Mac) или <kbd>CTRL</kbd><kbd></kbd>+</kbd> (Windows/ Linux)
    

  • Избегайте: , представленный следующим образом:<kbd>Ctrl</kbd>+<kbd>B</kbd> or <kbd>Command</kbd>+<kbd>B</kbd>

          <kbd>Ctrl</kbd>+<kbd>B</kbd> или <kbd>Command</kbd>+<kbd>B</kbd>
    

Лицензированное содержимое

          GitHub Docs лицензирован по [ лицензииCC-BY](https://github.com/github/docs/blob/main/LICENSE). Если вы повторно используете или изменяете лицензированное содержимое в статье, необходимо убедиться, что лицензия совместима и правильно связана.

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

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

Атрибутирование лицензированного с помощью MIT содержимого

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

В конце статьи, содержащей содержимое с лицензией MIT

• Создание заголовка Legal notice
• Атрибут, из которого поступает содержимое, и что он лицензируется в соответствии с лицензией MIT. Включение ссылки на проект
• Вставьте полный текст лицензии MIT из проекта, на который вы указываете в блоке кода

Пример ссылки на лицензию MIT

Этот текст является только примером. Всегда используйте текст лицензии из проекта, который вы используете.

## Legal notice

Portions have been adapted from [PROJECT](/LINK/TO/PROJECT) under the MIT license:

```
MIT License

Copyright YEAR COPYRIGHT-HOLDER

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
```

Разрывы линии

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

Ссылки.

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

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

Перед добавлением ссылки решите, нужно ли кому-то перейти по ней, чтобы понять содержание, или добиться успеха с .GitHub

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

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

Некоторые рекомендации по использованию ссылок:

• Ссылки должны быть значимыми и обеспечить высокую ценность для пути пользователя. Связывая вдумчиво.
• Не повторяйте одну и ту же ссылку несколько раз в той же статье.
• Рассмотрите возможность добавления "более ранних и более поздних версий в этой статье" после ссылки на раздел в той же статье.
• Не включайте apiVersion параметр запроса в ссылки REST, если вам не нужно ссылаться на определенную версию календаря документации REST. (Это должен быть редкий случай.)

Ссылки форматирования

Вы можете ввести ссылки только с командой "see", если контекст дает понять, что такое ссылка. Если контекст не понятен, используйте фразу или предложение, чтобы ввести ссылку, например "Дополнительные сведения, см. в разделе" или "Дополнительные сведения о X, см. статью "Y".

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

Не применяйте стили для ссылок или заключайте их в кавычки.

• Ссылки на другие страницы: See [AUTOTITLE](/PATH/TO/PAGE).
• Ссылки на разделы на других страницах: For more information, see [AUTOTITLE](/PATH/TO/PAGE#SECTION-LINK).

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

Не включайте знаки препинания в гиперссылку.

• Использование:OAuth2 tokens can be acquired programmatically for applications that are not websites. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) and [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps).
• Избегать:Read [more about OAuth2](/apps/building-integrations/setting-up-and-registering-oauth-apps/). Note that OAuth2 tokens can be [acquired programmatically](/enterprise-server@2.22/rest/reference/oauth-authorizations/#create-a-new-authorization), for applications that are not websites.

Связи между версиями

Иногда нужно связать одну версию GitHub Docs с другой. Если вы хотите связаться с другой версией той же страницы, следует использовать currentArticle свойство.

Например, версия Управление публикацией сайтов GitHub Pages для вашей организации для Free, Pro и Team может ссылаться на GitHub Enterprise Cloud версию той же статьи, как следующее:

You can choose to allow or disallow the publication of GitHub Pages sites.

Organizations that use {% data variables.product.prodname_ghe_cloud %} can choose to allow publicly published sites, privately published sites, both, or neither. For more information, see [the {% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/{{ currentArticle }}).

Чтобы связаться с другой статьей в другой версии, используйте следующий формат:

For more information, see [ARTICLE TITLE](/) in the VERSION documentation.

Чтобы связаться с той же статьей в другой версии, используйте следующий формат:

For more information, see [the VERSION documentation](/VERSION/{{ currentArticle }}).

Чтобы связать с определенной версией, необходимо включить версию в путь (например, /enterprise-cloud@latest/{{ currentArticle }}).

Ссылки на определенные разделы статей

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

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

For more information, see [HEADER TITLE](#HEADER-TITLE), later in this article.

Ссылки на один и тот же раздел не работают.AUTOTITLE Вместо этого необходимо ввести полный текст заголовка.

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

For more information, see [AUTOTITLE](PATH-TO-ARTICLE#HEADER-TITLE).

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

For more information, see [HEADER-TITLE-1](PATH-TO-ARTICLE#SECTION-LINK-1) and [HEADER-TITLE-2](PATH-TO-ARTICLE#SECTION-LINK-2) in "ARTICLE-TITLE."

Ссылки на определенное средство

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

For more information, see the TOOLNAME documentation in [ARTICLE TITLE](/PATH/TO/ARTICLE?tool=TOOLNAME).

Ссылки на схемы обучения

Используйте этот формат, чтобы связаться с схемой обучения.

For more information, follow the [LEARNING PATH TITLE](/) learning path.

Ссылки для перехода на внешние ресурсы

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

При упоминании внешнего продукта нет необходимости ссылаться на веб-сайт внешнего продукта.

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

• Использование:See [PAGE-TITLE](https://some-docs.com/PATH/TO/PAGE) in the XYZ documentation.
• Избегать:See [PAGE-TITLE](https://some-docs.com/PATH/TO/PAGE).
• Избегать:See [the OTHER WEBSITE](https://some-docs.com/PATH/TO/PAGE).

Добавление привязок для сохранения ссылок

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

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

<!-- Anchor to maintain the current example link. -->
<a name="SECTION-TITLE-THAT-MIGHT-CHANGE"></a>

Списки

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

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

• foo: что-то, которое предоставляет бар.
• bar: Что-то, предоставленное foo.

Форматирование неупорядоченных списков:

• Если порядок элементов в списке не важен, по алфавиту укажите элементы списка.
• Если порядок важен, упорядочение списка по важности читателю (например, переход от самой широкой аудитории и применимости к более специализированной аудитории).
• Используйте звездочки (*) для элементов списка.

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

          **Используйте**:

• Для введения к GitHub, см. следующие статьи:

• Проверка подлинности SMS поддерживается в следующих странах:

          **Избегать:**
  

• Существует несколько статей, которые дают введение в GitHub. См. следующие разделы:

• Проверка подлинности SMS поддерживается в 50 странах. Например:

Операторы разрешений и выноски продуктов

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

• Инструкции разрешений: роль, необходимая для выполнения действия или выполнения задачи, описанной в статье. Пример: "Владельцы предприятия".
• Выноска продукта: продукт или продукты, необходимые для выполнения действия или выполнения задачи, описанной в статье. Пример: «Корпоративные и корпоративные аккаунты с подпиской на Copilot Business.»

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

Рекомендации по созданию сканируемых выносок продуктов

Определение разрешений и требований к продукту

Рассмотрим, какие сведения принадлежат в инструкции разрешения или выноске продукта.

Например, при создании разрешений и продуктовых указаний для статьи AUTOTITLE, заявление о разрешении отвечает на «Какую роль может управлять политиками и функциями GitHub Copilot в организации?» А в объявлении о продукте отвечали бы: «Какие Copilot подписки нужны пользователям для управления Copilot политиками и функциями организации?»

Сосредоточьтесь на ключевых сведениях, а не объяснениях

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

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

Использование встроенных ссылок

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

Заполнители

Стиль любого замещающего текста во всех крышках. Если заполнитель имеет несколько слов, подключите слова с дефисами (kebab-case). Если вы используете заполнитель, объясните, на что кто-то может заменить его. Это помогает людям изменять примеры в соответствии с их потребностями и помогает выявлять заполнители для людей, использующих вспомогательные технологии.

          **Используйте**:

• В следующем примере замените YOUR-REPOSITORY именем репозитория. git init YOUR-REPOSITORY

• Нажмите кнопку "Добавить ИМЯ ПОЛЬЗОВАТЕЛЯ". Где ИМЯ ПОЛЬЗОВАТЕЛЯ является именем пользователя, которого вы хотите добавить.

          **Избегать:**
  

• git init your repository

• git init <your-repository>

• Нажмите кнопку "Добавить имя пользователя".

Процедурные шаги

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

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

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

1. Если шаг является необязательным, укажите, что сначала.

2. При необходимости для ясности или для усиления серьезности разрушительного или запутанного действия объясните причину или результат шага.

3. Опишите расположение, в котором пользователь найдет действие.

4. Действие.

          **Использование:** необязательно, для `REASON`, в `LOCATION`, принимать `ACTION`.
   

Примеры:

• Нажмите кнопку " Платежная информация".
• В имени организации нажмите кнопку "Параметры".
• Чтобы подтвердить изменение, нажмите кнопку " Удалить кредитную карту".
• При необходимости, чтобы просмотреть сведения о плане, нажмите кнопку "Показать сведения".
• В разделе «GitHub Sponsors» справа от спонсора открытый код нажмите рядом со спонсированной суммой, затем нажмите Сменить уровень.

Названия продуктов

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

Используйте переменные имени продукта для отрисовки имен продуктов— не записывайте названия продуктов в виде обычного текста. Это упрощает реализацию имен продукта на сайте и избегает опечаток в именах продуктов. Дополнительные сведения о переменных имени продукта см. в разделе "Многократно используемые и переменные" в этом документе и каталоге данных репозиторияgithub/docs.

Названия продуктов всегда являются уникальными.

• **Применение:**GitHub Actions помогает автоматизировать рабочие процессы разработки программного обеспечения.
• **Избегайте:**GitHub Actions Помочь автоматизировать рабочие процессы разработки программного обеспечения.

Необходимо различать имена продуктов и функции продукта. Функции продукта всегда являются строчным регистром.

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

Соглашения, относящиеся к продукту

В этом разделе описываются дополнительные соглашения, относящиеся к продуктам GitHub.

GitHub Actions

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

Примеры кода, использующие действия первой стороны, должны использовать соответствующие многократно используемые для этого действия. Это облегчает управление обновлениями версий action (например, от v1 к v2) для таких продуктов, как GitHub Enterprise Server, которые могут не иметь версии action до будущего GitHub Enterprise Server релиза.

Действия, которые можно использовать повторно, находятся /data/reusables/actions/ и имеют имя файла, например action-<action_name>.md

Например, чтобы использовать actions/checkout действие в примере, используйте его повторное использование:

steps:
  - name: Checkout
    uses: actions/checkout@v6

Для GitHub Docs целей действие первой стороны — это любое действие с actions/префиксом , github/ или octo-org/ . Например, это действие первой стороны:

steps:
  - uses: actions/checkout@v6

Отказ от ответственности для сторонних действий

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

# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.

Чтобы вставить этот отказ, используйте повторно используемый {% data reusables.actions.actions-not-certified-by-github-comment %} объект.

Для GitHub Docs целей действие третьей стороны — это любое действие, не имеющее actions/префикса , github/ или octo-org/ . Например, это действие первой стороны:

steps:
  - uses: actions/checkout@main

Это пример действия стороннего производителя:

steps:
    - uses: google-github-actions/setup-gcloud@1bee7de035d65ec5da40a31f8589e240eba8fde5

Примеры:

• См. блок кода в публикации в реестрах пакетов

Закрепление номеров версий в SHA

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

steps:
    - uses: google-github-actions/setup-gcloud@1bee7de035d65ec5da40a31f8589e240eba8fde5

Для GitHub Docs целей действие третьей стороны — это любое действие, не имеющее одного из следующих префиксов: actions/, github/, и octo-org/. Например, это действие первой стороны:

steps:
  - uses: actions/javascript-action@main

Дополнительные сведения см. в статье об использовании shas

Codespaces

При упоминании произведения Codespacesвсегда включать «GitHub», за исключением следующих случаев:

• В переднем вопросе shortTitle .
• В подзаголовках внутри статьи, если «Codespaces» уже использовался где-либо в статье до появления подзаголовка.

Переменные: {% data variables.product.prodname_github_codespaces %} ("Пространства кода GitHub") и {% data variables.product.prodname_codespaces %} ("Codespaces").

При обращении к экземплярам удаленных рабочих сред, созданных с помощью этой технологии, обратитесь к ним как к "пространствам кода" (строчным буквам c). Например, "чтобы удалить пространство кода" или "перечислить пространства кода".

Всегда используйте "контейнер разработки" (или, где требуется уточнение, более длинная форма "контейнер разработки") и не "devcontainer" (одно слово), за исключением имен файлов и путей. Одно слово может считаться брендом, чего мы хотим избегать, а также хотим быть последовательными в двухсловной форме, используемой в Visual Studio Code документации.

Используйте файлы конфигурации контейнера разработки, чтобы ссылаться на все файлы в .devcontainer каталоге (а также использовать .devcontainer.json его, а не devcontainer.json в каталоге .devcontainer ). Не ссылайтесь на эти файлы как "файлы контейнера разработки" или "файлы devcontainer", чтобы избежать их использования в качестве ссылок на devcontainer.json файлы. Файлы конфигурации контейнера разработки относятся ко всем файлам, которые можно использовать для настройки контейнера разработки, в том числе Dockerfile и compose.yaml файлов. Не используйте файл конфигурации контейнера разработки (сингулярный) при обращении конкретно к файлу devcontainer.json . Вместо этого следует ссылаться на этот файл по имени.

          GitHub Advanced Security Продукция (GHAS)

Используйте термины licenses и active committers когда вы имеете в виду GitHub Advanced Security, GitHub Code Security, или GitHub Secret Protection биллинг.

Раньше мы использовали этот seats термин, чтобы описать количество аккаунтов, которые могут использовать GitHub Advanced Security, GitHub Code Security, или GitHub Secret Protection в предприятии. Люди могут быть смущены термином seats, поэтому мы удалили этот термин из GitHub.com осенью 2022 года и версии из GHES 3.7 не используют его.

Personal access tokens

          GitHubимеет два типа:personal access tokens

• Fine-grained personal access tokens: Предоставить детальный контроль над доступом к репозиторию и разрешениями
• Personal access token (classic): Используйте области и предоставляйте доступ ко всем репозиториям, к которым владелец токена имеет доступ

Вам следует использовать переменные для обозначения этих типов токенов, а также в целом personal access tokens :

• Использовать {% data variables.product.pat_generic %}или {% data variables.product.pat_generic_caps %} называть personal access token это в общем смысле. Используйте {% data variables.product.pat_generic_title_case %} если фраза должна быть в заглавном регистре ("Personal Access Token") для соответствия тексту интерфейса.
• Используйте {% data variables.product.pat_v2 %} или {% data variables.product.pat_v2_caps %} называйте fine-grained personal access tokens.
• Используйте {% data variables.product.pat_v1 %}, {% data variables.product.pat_v1_plural %}, {% data variables.product.pat_v1_caps %}, или {% data variables.product.pat_v1_caps_plural %} для обозначения personal access token (classic).

Для получения дополнительной информации о GitHub's personal access tokensсм. Управление личными маркерами доступа.

Пунктуация

Следуйте стандартным правилам препинания американского английского языка. Дополнительные рекомендации см. в разделе "Знак препинания" в руководстве по стилю Майкрософт.

Заметки о выпуске

Набор заметок по релизу, которые GitHub Docs рассказывают читателям о изменениях администратора или пользователя в версионном выпуске продукта, например GitHub Enterprise Server (GHES). Заметки о выпуске отображаются в AUTOTITLE.

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

Каждое примечание о выпуске в наборе описывает одно из следующих изменений.

• Функции: совершенно новое поведение или функциональные возможности
• Исправления безопасности: исправление ошибок или непредвиденного поведения, которые влияют на безопасность
• Исправления ошибок: исправление ошибок в ошибках или непредвиденном поведении
• Изменения: заметные изменения в прошлом поведении
• Известные проблемы: проблемы, которые GitHub были выявлены, но не могут или ещё не приоритизированы
• Закрытие: процесс выхода на пенсию и больше не следует полагаться на будущую работу
• Выведенные из эксплуатации: конец жизненного цикла продукта или функции
• Эррата: исправление неточного заметки о выпуске или документации

Вы также можете просмотреть рекомендации по обновлению заметок о выпуске при добавлении или обновлении заметки о выпуске и удалении заметки о выпуске.

Компоненты

Заметка о выпуске функции суммирует совершенно новое поведение. Как правило, заметки о функциях являются лишь частью выпусков компонентов.

Написание заметок о выпуске для функций

Примечание о выпуске функции отвечает на следующие вопросы.

1. Применяется ли эта новая функция ко мне, с моей ролью или доступом?
2. Что требуется для удовлетворения функциональных возможностей?
3. Что такое функциональные возможности?
4. Если применимо, где можно узнать больше о функциональных возможностях?

          _АУДИТОРИЯ_ (1 **) МОЖЕТ **ОПИСАНИЕ НЕОБХОДИМОСТИ** (__ 2**) ПО _ОПИСАНИЮ ИСПОЛЬЗОВАНИЯ_ ФУНКЦИИ (**3**). Дополнительные сведения см. в статье [_TITLE_](/) (**4**)

• Классифицируйте каждую функцию в разделе под заголовком компонента.
• Напишите в настоящее время.
• Чтобы уменьшить повторение и ненужные слова, "сейчас" обычно подразумевается.
• Чтобы уточнить субъекты и влияние, избегайте пассивного языка, когда это возможно.

Примеры примечаний о выпуске компонентов

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

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

• Пользователи могут создавать файлы с помощью схем geoJSON, topoJSON и STL и отрисовки схем в веб-интерфейсе. Дополнительные сведения см. в статье "Работа с файлами, не относящихся к коду".

Исправления безопасности

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

Написание заметок о выпуске для исправлений безопасности

Примечание о выпуске для исправления безопасности отвечает на следующие вопросы.

1. Если он доступен, что такое рейтинг серьезности уязвимостей NVD для исправленной уязвимости?
2. Что такое атака, которую злоумышленник может выполнить, используя уязвимость?
3. Какой тип уязвимости можно использовать?
4. Если доступно, какой идентификатор CVE уязвимости, ожидающий или активный?
5. Кто-то сообщит об уязвимости через программу bounty ошибки GitHub?

          _СЕРЬЕЗНОСТЬ_ (1 **): Злоумышленник может **ОПИСАНИЕ ВЛИЯНИЯ** (__ 2**) ПО _ОПИСАНИЮ ЭКСПЛОЙТОВ_ (**3**). GitHub запросил CVE ID _CVE-####-#####_** ([4](/)) для этой уязвимости, которая была сообщена через **программу** GitHub Bug Bounty ([5](https://bounty.github.com)).**

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

•         **СРЕДНИЙ.** Злоумышленник может привести к неограниченному исчерпанию ресурсов экземпляра, выполняя параллельные запросы к REST API Markdown. Чтобы смягчить эту проблему, GitHub обновил [CommonMarker](https://github.com/gjtorikian/commonmarker). 
  

          GitHub запросил CVE ID [CVE-2022-39209](https://nvd.nist.gov/vuln/detail/CVE-2022-39209) для этой уязвимости.
  

•         **СРЕДНИЙ.** Злоумышленник может внедрить опасные ссылки в веб-интерфейс экземпляра, так как ссылки предварительного просмотра запросов на вытягивание не исправно очищают URL-адреса. Эта уязвимость была зафиксирована через [программуGitHub Bug Bounty](https://bounty.github.com).
  

Обновления базового образа и пакета

Мы также добавим обновления базового образа и зависимых пакетов в раздел "Исправления безопасности", так как эти обновления часто устраняют проблемы безопасности. Мы консолидируем все эти обновления в следующем примечание.

В пакетах обновлены системы безопасности до последних версий.

Исправления ошибок

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

Написание заметок о выпуске для исправлений ошибок

Примечание о выпуске исправления ошибок отвечает на следующие вопросы.

1. Повлияло ли поведение на меня, с моей ролью или доступом?
2. Какое поведение будет выполнять читатель до исправления?

          _АУДИТОРИЯ_ (1 _) **ОПИСАНИЕ ПОВЕДЕНИЯ** (_**2**).

• Так как ошибка исправлена, запишите в прошлом времени.
• Язык, например "исправлена ошибка..." или "Исправлена проблема..." подразумевается и не требуется.
• Чтобы уменьшить повторение и ненужные слова, "сейчас" обычно подразумевается.
• Чтобы уточнить субъекты и влияние, избегайте пассивного языка, когда это возможно.
• Если заметка о выпуске содержит сообщение об ошибке, отформатируйте сообщение в соответствии с рекомендациями в сообщениях об ошибках.

Примеры заметок о выпуске исправлений ошибок

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

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

• Команды, которые администраторы сайта выполняли через SSH на любом из узлов экземпляров, не вошли в /var/log/ssh-console-audit.logсистему.

Изменения

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

Написание заметок о выпуске для изменений

Примечание о выпуске для изменения отвечает на следующие вопросы.

1. Повлияло ли поведение на меня, с моей ролью или доступом?
2. Если изменение решает или избегает проблемы, что такое проблема?
3. Что нового поведения?
4. Если это важно, то что такое поведение перед изменением?

          _АУДИТОРИЯ_ (1 _) / **ОПИСАНИЕ ИЗМЕНЕНИЯ ПРОБЛЕМЫ РЕШАЕТ** (_**2**) _ОПИСАНИЕ НОВОГО ПОВЕДЕНИЯ (3 **) _ОПИСАНИЕ СТАРОГО ПОВЕДЕНИЯ_** (_**4).**

• Так как изменение применяется к выпуску, напишите заметки об изменениях в настоящем напряженном времени.
• Чтобы уменьшить повторение и ненужные слова, "сейчас" обычно подразумевается.
• Чтобы уточнить субъекты и влияние, избегайте пассивного языка, когда это возможно.
• Часто аудитория подразумевается.
• Если полезно, включите соответствующие ссылки на документы GitHub.

Примеры заметок о выпуске изменений

• В экземпляре с лицензией на GitHub Advanced Security или GitHub Secret Protection, пользователи, создающие индивидуальные шаблоны для секретного сканирования, могут предоставлять выражения, которые должны или не должны совпадать и составляют до 2000 символов. Это ограничение увеличивается с 1000 символов.

• Для администраторов, которым нужно просмотреть или изменить сопоставления SAML, вместо выходных данных ghe-saml-mapping-csv -d используется /data/user/tmp``/tmpпуть по умолчанию. Дополнительные сведения см. в разделе служебных программ командной строки.

• Чтобы избежать периодических проблем с успехом операций Git на экземпляре с несколькими узлами, GitHub Enterprise Server перед попыткой выполнить SQL-запрос проверяет статус контейнера MySQL. Время ожидания также сократилось.

Известные проблемы

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

Написание заметок о выпуске для известных проблем

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

1. Влияет ли поведение на меня, с моей ролью или доступом?
2. Какие сообщения об ошибках или другие узнаваемые элементы пользовательского интерфейса отображаются?
3. Нужно ли действовать? Если да, что делать?

          _АУДИТОРИЯ_ (1 **) ОПИСАНИЕ ПРОБЛЕМЫ** (** 2 _) _ПОДРОБНОСТИ ПОВЕДЕНИЯ_ (**** 3_) **_ДАЛЬНЕЙШИЕ ДЕЙСТВИЯ_ (**4**).

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

Примеры заметок о выпуске известных проблем

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

• После запуска конфигурации No such object error администратор может произойти во время этапа проверки служб Записной книжки и просмотра. Эта ошибка может быть проигнорирована, так как службы по-прежнему должны правильно запускаться.

Закрытие

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

Написание заметок о выпуске, которые закрываются

Примечание о выпуске функции, закрывающей ответы на следующие вопросы.

1. Применяется ли эта функциональность ко мне с моей ролью или доступом?
2. Что такое функциональность, которая закрывается?
3. Если применимо, что заменяет функциональность закрытия?
4. Если применимо, где можно прочитать больше?

          _АУДИТОРИЯ_ (1 _) ОПИСАНИЕ ЗАКРЫВАЮЩЕЙ ФУНКЦИИ** (** 2 _) _**ФУНКЦИИ ЗАМЕНЫ** (_**3**) Дополнительные сведения см. в РАЗДЕЛЕ [_ЗАГОЛОВКА_](/) СТАТЬИ (**4).**

• Заметки находятся в настоящем времени или будущие напряженные для предстоящих изменений. Если применимо, укажите предстоящий выпуск при выходе на пенсию.
• Чтобы уменьшить повторение и ненужные слова, "сейчас" обычно подразумевается.
• Чтобы уточнить субъекты и влияние, избегайте пассивного языка, когда это возможно.
• Классифицируйте каждую функцию в разделе под заголовком компонента.

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

•         **Закрытие:** В GitHub Enterprise Server версиях 3.8 и выше, чтобы обеспечить безопасность экземпляра, незащищённые алгоритмы будут отключены для SSH-соединений с административной оболочкой.
  

• Зафиксируйте комментарии, которые пользователи добавляют непосредственно в фиксацию за пределами запроса на вытягивание, больше не отображаются в временной шкале запроса на вытягивание. Пользователи не смогли ответить на эти комментарии или устранить их. REST API событий временной шкалы и объект API PullRequest GraphQL больше не возвращают комментарии фиксации.

Поддержка прекращена

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

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

Заметка о выпуске для устаревшей функции отвечает на следующие вопросы.

1. Применяется ли эта функция ко мне, с моей ролью или доступом?
2. Что такое функциональность, которая прекращена?
3. Если применимо, что заменяет устаревшие функции?
4. Если применимо, где можно прочитать больше?

          **АУДИТОРИЯ (1) ОПИСАНИЕ УСТАРЕВШИХ ФУНКЦИЙ_ (2 _) _**ФУНКЦИИ ЗАМЕНЫ** (_**3**) Дополнительные сведения см. в РАЗДЕЛЕ**_ "НАЗВАНИЕ_** СТАТЬИ" (_4)_[](/)**

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

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

•         **Завершили карьеру:**GitHub Больше не поддерживает необходимые рабочие процессы для GitHub Actions версий GitHub Enterprise Server 3.11 и более поздних. Вместо этого используйте наборы правил репозитория. Дополнительные сведения см. в разделе [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-workflows-to-pass-before-merging).
  

Ошибки

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

Написание эрраты

Эррата отвечает на следующие вопросы.

1. Если применимо, какой раздел заметок или содержания GitHub Docs релиза был затронут?
2. Применена ли к мне неправильная информация с моей ролью или доступом?
3. Что описано в заметке о выпуске или документации, которая была неправильной?
4. Когда был опубликован эррата?

          _СОДЕРЖИМОЕ_ (1 **) неправильно указало, что **АУДИТОРИЯ** (__ 2**) может _СВОДКА НЕТОЧНОЙ ИНФОРМАЦИИ_ (**3**). [Обновлено: _ДАТА_**ПУБЛИКАЦИИ 4**]

• Отформатируйте дату публикации в соответствии с рекомендациями по добавлению или обновлению заметки о выпуске.

Пример эрраты

•         [Функции](/) ошибочно указывали, что пользователи GitHub Advisory Database могут видеть рекомендации для Elixir, менеджера пакетов Hex от Erlang и других. Эта функция недоступна в GitHub Enterprise Server 3.7 и будет доступна в будущем выпуске. [Обновлено 2023-06-01]
  

Добавление или обновление заметки о выпуске

Чтобы сообщить читателям, что вы добавили или изменили заметку, или укажите дату публикации errata, добавьте метку даты в формате "[Обновлено: ГГГГ-ММ-ДД]".

Удаление заметки о выпуске

Чтобы сообщить о том, что мы удалили заметку о выпуске, добавьте раздел "Errata" с подробными сведениями о том, какие заметки вы удалили, и (если это необходимо), к какой версии удаленная заметка фактически относится. См. статью "Написание эрраты".

Ссылки на выпуск

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

• Использование: "выпуск 0.41.0 или более поздней версии"
• Избегайте: "выпуск 0.41.0 или более поздней версии"
• Избегайте: "выпуск 0.41.0 или больше"

Повторно используемые и переменные

Используйте многократно используемые строки для отдельных существительных (например, имен продуктов) или для полных предложений или абзацев. Фрагменты предложений и фразы не должны содержаться в многократно используемых строках, так как они могут вызвать проблемы при локализации содержимого. Дополнительные сведения см. в каталоге данных вgithub/docsрепозитории, создании повторно используемых содержимого и разделе "Имена продуктов" этого документа.

Секционные tocs

Если раздел статьи использует H3 или H4 заголовки для дальнейшего разделения содержимого и только часть содержимого относится к читателю, вы можете использовать разделальную оглавление (TOC), чтобы помочь читателям определить и перейти к информации, которая наиболее актуальна для них. Например, в Потоковая передача журнала аудита для предприятия пользователи, вероятно, будут настраивать потоковую передачу журналов аудита только для одного поставщика, поэтому раздел "Настройка потоковой передачи журналов аудита" позволяет людям выбрать своего поставщика и перейти к соответствующему содержимому без чтения всего раздела.

Если или заголовки используются только для группирования содержимого, H3 а H4 все сведения могут быть релевантны для читателя. Например, в Основы управления идентификацией и доступом люди должны читать и рассматривать каждый раздел, так как он связан с их предприятием. В эту статью мы не включаем раздел toC, так как люди должны читать каждый раздел, а не выбирать и выбирать между ними. Добавление разделителя TOC также заставит людей, использующих экранные средства или другую адаптивную технологию, на вкладку и прокрутите дополнительные заголовки перед поиском необходимых им элементов.

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

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

Пример секционных токов

## Setting up the application

Set up your application according to your operating system.

* [Setting up for macOS](#setting-up-for-macOS)
* [Setting up for Windows](#setting-up-for-windows)
* [Setting up for Linux](#setting-up-for-linux)

### Setting up for macOS

TEXT

### Setting up for Windows

The application is supported for all versions of Windows, but the set up steps differ.

* [Windows 98](#windows-98)
* [Windows Vista](#windows-vista)
* [Windows 11](#windows-11)

#### Windows 98

TEXT

#### Windows Vista

TEXT

#### Windows 11

TEXT

### Setting up for Linux

TEXT

Таблицы

Таблицы добавляются в GitHub Docs Markdown с помощью Markdown. Так как таблицы могут быть сложными для чтения и обслуживания, убедитесь, что данные в таблице лучше всего представлены в таблице, а не в другом формате, например списке, перед созданием таблицы. Каждая строка в таблице должна начинаться и заканчиваться каналом. |

Использование таблиц только для представления табличных сведений

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

Избегайте описания данных таблицы

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

Например, в Справочник по локальным запускам таблица, сравнивающая функции между двумя поддерживаемыми решениями автомасштабирования, представлена в предложении Each solution has certain specifics that may be important to consider. , в статье не описываются различные функции, которые сравниваются, так как эта информация четко передается таблицей.

• Используйте команду "Разные ограничения размера для каждого репозитория применяются в зависимости от версии GHES".
• Избегайте: "Первая строка таблицы отображает сведения для GitHub Enterprise Cloud. Вторая строка отображает сведения для GitHub Enterprise Server".
• Избегайте: "В таблице ниже показано, какой тип данных миграции экспортируется".

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

Таблицы, в которых первый столбец описывает значения данных в таблице (но не данные сами по себе) должны быть помечены заголовками строк. Это важно для вспомогательных технологий, чтобы понять связи между ячейками.

Например, в следующей таблице, чтобы определить значения "Да" и "Нет" в таблице, необходимо знать как заголовок столбца (роль), так и заголовок строки (разрешение).

Чтобы добавить заголовки строк для таблицы Markdown, обертайте таблицу в теги {% rowheaders %} {% endrowheaders %}Liquid. Дополнительные сведения об использовании заголовков строк см. в разделе Использование Markdown и Liquid в документах GitHub.

Включение значения для каждой ячейки

Каждая ячейка в таблице должна содержать значение.

Для ячеек без данных используйте "Нет" или "Неприменимо". Не используйте "NA" или "N/A".

Для таблиц с заголовками строк первая ячейка (ячейка "A1") должна описать заголовки строк, чтобы помочь людям понять всю таблицу. Тем не менее, если это сделать таблицу менее ясной или добавить избыточные сведения, вы можете оставить эту ячейку пустой. Например, в статье Создание и тестирование для PowerShell первая ячейка может быть помечена как "Модули", но так как каждый заголовок строки уже содержит слово "module", этот заголовок повторит информацию, которая не добавляет описательное значение для понимания таблицы в целом.

Использование четких, согласованных символов и меток

Для таблиц, использующих символы:

• Заполните все ячейки. Например, в таблице разрешений не помечайте только ячейки для вещей, требующих разрешения.
• Используйте октиконы или SVG. Не используйте эмодзи. Дополнительные сведения о октиконах см. в разделе Использование Markdown и Liquid в документах GitHub.
• Используйте флажок для положительных значений ("Да", "Обязательный", "Поддерживаемый") и крест для отрицательных значений ("Нет", "Необязательный", "Неподдерживаемый").
• Используется aria-label для описания смысла символа, а не его визуальных характеристик. Например, "Обязательный", а не "Значок флажка".

Если данные таблицы не являются действительно двоичными (каждое значение — "Да" или "Нет", например, текстовые значения могут потребоваться в дополнение или вместо символов. Например, на странице О поддержке GitHub некоторые функции помечены как "Доступные для покупки".

Использование сносок смешно

См . сноски.

Согласованное выравнивание содержимого таблицы

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

Содержимое таблицы по умолчанию выравнивается по левому краю. Используйте форматирование таблицы Markdown, двоеточие (:) справа или слева от дефисов в строке заголовка, чтобы указать выравнивание каждого столбца. Дополнительные сведения см . в AUTOTITLE .

В следующем примере показана часть таблицы из Справочник по параметрам зависимостей.

Таблица создается с помощью следующего синтаксиса выравнивания.

| Option              | Required | Security Updates | Version Updates | Description                    |
|---------------------|:--------:|:----------------:|:---------------:|--------------------------------|
| `package-ecosystem` |{% octicon "check" aria-label="Supported" %}|{% octicon "x" aria-label="Not supported" %}|{% octicon "check" aria-label="Supported" %}| Package manager to use         |
| `directory`         |{% octicon "check" aria-label="Supported" %}|{% octicon "x" aria-label="Not supported" %}|{% octicon "check" aria-label="Supported" %}| Location of package manifests  |
| `schedule.interval` |{% octicon "check" aria-label="Supported" %}|{% octicon "x" aria-label="Not supported" %}|{% octicon "check" aria-label="Supported" %}| How often to check for updates |

Titles

Используйте регистр предложений для заголовков.

Короткие названия

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

• Короткие названия длиной 2-3 слова.
  • Для категорий короткие заголовки должны быть меньше 27 символов.
  • Для тем карты короткие заголовки должны быть меньше 30 символов.
  • Для статей короткие названия должны быть менее 31 символов и в идеале от 20 до 25 символов.
• Короткие названия используют базовую форму глаголов вместо герунд.
  • Используйте команду "Настройка уведомлений" вместо "Настройка уведомлений".
• Короткие названия категорий, разделов карт и статей могут опустить названия продуктов и функций, если это ясно, с каким продуктом или компонентом они связаны.
  • Применение: «Configure notifications» — это короткое название для AUTOTITLE , так как статья находится в теме карты «Dependabot alerts».
• Короткие названия не вводят новые слова, которые не находятся в полном названии.
• Короткие заголовки должны быть параллельны короткими заголовками для аналогичного содержимого.
  • Использование: "Организации и команды" и "Корпоративные учетные записи"
  • Избегайте: "Организации и команды" и "Управление корпоративными учетными записями"

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

Содержимое политики сайта

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

Содержание политики сайта использует тот же стиль и модели содержания, что и остальная GitHub Docsчасть .

Элементы пользовательского интерфейса

Полужирный шрифт

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

• На левой боковой панели щелкните Выставление счетов.
• Просмотрите поле слияния в нижней части вкладки беседы** запроса **на вытягивание.
• Рядом с title добавьте описательную метку для нового ключа.

Имена ветвей

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

• main
• USERNAME.github.io

Пуговицы

Отформатируйте имена кнопок полужирным шрифтом и, когда это возможно, опустите слово "кнопка". Чтобы описать использование кнопки, напишите "щелчок", а не нажимайте или нажимайте.

• Использование: щелкните запрос на вытягивание.
• Избегайте: нажмите кнопку "Запрос на вытягивание".

Флажки

Отформатируйте имена флажков полужирным шрифтом и опустите слово "флажок". Чтобы описать выбор или очистку флажка, используйте команду select или deselect.

• Использование: выберите "Включить" для всех новых репозиториев.
• Избегайте. Установите флажок "Включить для всех новых репозиториев".

Динамический текст

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

• Использование: нажмите кнопку "Добавить ИМЯ ПОЛЬЗОВАТЕЛЯ" в REPONAME.

Списки и элементы списка

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

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

Расположение

          [Согласно рекомендациям](https://www.w3.org/WAI/WCAG21/Understanding/sensory-characteristics.html) WCAG, мы должны описать элементы по имени, а не только по внешнему виду или расположению. Руководство по стилю Майкрософт предлагает конкретные рекомендации по направлениям фраз, с акцентом на их использование в документации.

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

Панели

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

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

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

• Использование. На панели "Покрытие безопасности" выберите "Включить или отключить".
• Используйте: на панели нажмите кнопку "Включить " или "Отключить".

Переключатели

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

Имена репозитория

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

• Использование. Дополнительные сведения см. в репозиторииgithub/docs.

Адаптивные элементы

Мы документируем только адаптивные состояния элементов пользовательского интерфейса при создании неоднозначности или путаницы. Если задача неясна из-за адаптивного элемента пользовательского интерфейса, опишите взаимодействие, которое кто-то должен сделать для достижения цели задачи. Не просто описывайте визуальное состояние элемента пользовательского интерфейса.

• Использование: нажмите кнопку " Безопасность". Если безопасность не видна, щелкните ⋮ , чтобы развернуть меню репозитория.

Текст пользовательского интерфейса

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

• Используйте: в разделе "Список разрешенных IP-адресов" нажмите кнопку "Изменить".

Дополнительные ресурсы

Руководство по стилю Майкрософт:

• Форматирование текста в инструкциях

Видео

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

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

Стиль и тон

Используйте понятный, простой язык, который подходит для широкого спектра читателей. Будьте аутентичными, эмпатичными и уверенными в своем написании.

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

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

Мы глобальное сообщество разработчиков. Избегайте поворотов фраз, идиом и сленга, характерных для определенного региона или страны.

Дополнительные сведения о написании приближаемого содержимого см. в статье "[Голос фирменной символики Майкрософт: прежде всего, простые и человеческие и 10 советов по стилю и голосу](https://docs.microsoft.com/style-guide/top-10-tips-style-voice) Майкрософт".

Выбор и терминология Word

Общие рекомендации и термины для GitHub см. в нашем глоссарии. Дополнительные инструкции см. в руководстве по стилю Майкрософт по списку слов A-Z.

Abbreviations

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

• Использование: репозиторий
• Избегайте: репозиторий
• Использование: администратор, пользователи с разрешениями администратора
• Избегайте: администраторы

Не используйте символы или октиконы, которые не используются в пользовательском интерфейсе GitHub.

• Использование: щелкните файл, а затем нажмите кнопку "Изменить".
• Избегайте: нажмите кнопку " Файл" > "Изменить".

Организация

Имена продуктов и учетные записи

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

• Применение: Ваша организация GitHub Enterprise Cloud
• Избегайте: Ваш GitHub Enterprise Cloud аккаунт
• Избегайте: Ваша GitHub Enterprise Server организация
• Использовать: Вы можете выделить свою работу на GitHub Enterprise Server, отправив подсчёты вкладов в свой GitHub.com-профиль.

Индивидуальные аккаунты на GitHub

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

Если контент не касается управления корпоративным продуктом, опишите аккаунт GitHub отдельного человека как «личный аккаунт». Это создает согласованность с пользовательским интерфейсом и предотвращает смущение читателей, видя два термина, которые означают одно и то же.

• Использование: управление запланированными напоминаниями для личная учетная запись
• Избегайте: управление запланированными напоминаниями для учетной записи пользователя

Учетные записи для корпоративных продуктов

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

• GitHub Enterprise Cloud
• GitHub Enterprise Server

Если читатель управляет корпоративной учетной записью, и вы описываете учетные записи пользователей, которыми они управляют, используйте "учетную запись пользователя". Это относится к следующим продуктам.

• GitHub Enterprise Cloud с Enterprise Managed Users
  • Применение: С Enterprise Managed Usersпомощью , вы можете создавать и управлять аккаунтами пользователей для своих корпоративных участников.
  • Избегайте: С Enterprise Managed Usersпомощью , вы можете создавать и управлять личными аккаунтами для членов вашей компании.
• GitHub Enterprise Server
  • Использование: если вам нужно временно взять на себя учетную запись пользователя...
  • Избегайте: Если вам нужно временно взять на себя личная учетная запись...

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

• Продукт AUTOTITLE
• Документация по выставлению счетов для конкретного предприятия, например Биллинг для GitHub Enterprise
• Содержимое в других продуктах, предназначенных для административной аудитории, например [AUTOTITLE в продукте "Безопасное кодирование" или Рекомендации по защите учетных записей](/enterprise-cloud@latest/admin/overview/setting-up-a-trial-of-github-enterprise-cloud) в продукте "Начало работы"
• Содержимое API для конкретного предприятия, например справочная документация по REST API AUTOTITLE

Для предприятий GitHub Enterprise Cloud , которые не используют Enterprise Managed Users, используйте «личный аккаунт» при описании членов организаций, принадлежащих компании.

• Применение: Если вы настроите SAML SSO, члены вашей организации будут продолжать входить в свои личные аккаунты на GitHub.com.
• Избегайте: Если вы настроите SAML SSO, члены вашей организации будут продолжать входить в свои пользовательские аккаунты на GitHub.com.

Документация, описывающая GitHub Enterprise Cloud без Enterprise Managed Users заголовка, обычно относится к категории AUTOTITLE .

Учетные записи людей для других служб

Когда вы описываете аккаунт человека для сервиса, отличного GitHubот , например, провайдера интеграции или аутентификации, используйте «учетная запись пользователя».

Акронимы

Выясним акронимы при первом использовании в статье, за исключением заголовков или заголовков.

Приложения

Используйте "app" или "application" в общем содержимом.

• Применение: Опубликуйте и разместите своё приложение в GitHub Marketplace

Используйте «app» при упоминании OAuth apps , так как это не продукт.

• Применение: Зарегистрировать OAuth app
• Избегайте: регистрация Приложение OAuth

Используйте «App» при упоминании GitHub Apps , так как это продукт.

• Применение: Зарегистрировать а GitHub App

          GitHub Apps и OAuth apps состоят из двух частей: регистрации приложения и кода, который заставляет приложение что-то делать.
  

• Чтобы отнестись только GitHub App к настройкам/конфигурациям в GitHub интерфейсе, используйте термины вроде «регистр» и «GitHub App регистрация».

  • Применение: Зарегистрировать а GitHub App
  • Применение: Обновить регистрацию GitHub App
  • Избегайте: Создайте GitHub App
  • Избегайте: Модифицировать GitHub App

• Чтобы ссылаться только на код приложения, используйте терминологию, например "код для приложения" или "код приложения".

  • Использование: код для приложения
  • Используйте код для вашего GitHub App
  • Использование: код приложения
  • Избегайте: Твой GitHub App
  • Избегайте: Твой OAuth app

• Чтобы обозначить всё приложение в целом (регистрация + код), называйте его a GitHub App или OAuth app.

          GitHub Apps Можно установить в организационные и пользовательские аккаунты. Чтобы обозначить установку приложения, используйте "GitHub App installation" вместо "GitHub App."
  

Валюта

При обращении к долларам, центам, суммам валюты или использованию $ знака убедитесь, что используемая валюта определена даже в том случае, если сумма равна нулю. Используйте стандартное [имя валюты ISO и код](https://www.six-group.com/en/products-services/financial-information/data-standards.html#scrollTo=currency-codes) валюты стандарта ISO, где это возможно.

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

• Использование: доллар США.
• Избегайте: доллар США, $USD доллар.

Используйте верхний регистр для кодов валют.

• Использование: USD.

Если в статье есть только одна ссылка, используйте имя валюты без знака, предшествующего $ сумме.

• Используется:10 US dollars для одной ссылки на валюту.

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

Для последующих ссылок на валюту в статье или при необходимости (например, при рассмотрении пробела или при наличии нескольких сумм в таблице или списке), включите $ знак перед суммой и используйте стандартный код валюты ISO после суммы.

• Используйте:10 US dollars (USD) для первой ссылки и $0.25 USD для последующих ссылок.
• Избегайте:$10 US dollars (USD), USD$0.25.

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

• Используйте:99 cents (US currency) для первой ссылки и 99 cents для последующих ссылок.
• Избегайте:$0.99 (US currency), $0.99 USD cents, USD$0.99 cents.

Разрешения

Разрешение **** — это возможность выполнения определенного действия. Например, возможность удалить проблему является разрешением.

Роль **** — это набор разрешений, которые могут быть назначены пользователю. Роли существуют на разных уровнях.

• Учетные записи (например, владелец организации, менеджер по выставлению счетов для корпоративной учетной записи)
• Ресурсы (например, запись в репозиторий, администратор для рекомендаций по безопасности)
• Teams (например, ответственный за команду)

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

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

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

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

• Использование. Пользователи с доступом на запись в репозиторий могут выполнять X в репозиторий.
• Избегайте: владельцы организации и пользователи с доступом на запись могут выполнять X в репозитории.

Дополнительные сведения о выборе слов для инструкций разрешений см. в разделе Содержание статьи на GitHub Docs в con режим палатки l.

Предлоги

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

Названия продуктов

См. раздел "Имена продуктов" этого руководства.

Условия использования или предотвращения

выбор слов;

Неоднозначные глаголы

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

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

Невидимые множественное число

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

• Используйте: после получения файла выберите место его сохранения.
• Избегайте. После извлечения файла выберите место для сохранения.

Номинальные значения

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

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

Строки существительных

Избегайте модификаторов с накоплением (строк существительных), что может привести к неправильным переводам, так как переводы могут не указывать, какое слово изменяет другое. Строку существительных можно переразразить с помощью препозиции. Если используется модификатор с накоплением, убедитесь, что фоновая информация и контекст понятны, чтобы читатели и переводчик могли понять, что изменяется.

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

Расплывчатые существительные и существительные

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

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