Skip to content
This repository was archived by the owner on May 23, 2024. It is now read-only.

CONTRIBUTING.md

Latest commit

 

History

History
215 lines (136 loc) · 25.9 KB

CONTRIBUTING.md

File metadata and controls

215 lines (136 loc) · 25.9 KB
Raw

Улучшение документации по Microsoft Graph

Благодарим вас за интерес к документации по Microsoft Graph!

Как внести свой вклад

Вы можете внести свой вклад в документацию по Microsoft Graph следующими способами:

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

Небольшие исправления

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

Значительные изменения

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

  • участники группы Microsoft Open Technologies;
  • участники, не являющиеся сотрудниками Майкрософт.

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

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

Вы можете скачать лицензионное соглашение об участии (CLA) здесь. Заполните форму и отправьте ее по адресу officedev@microsoft.com.

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

Организация репозитория

Первоначальным основанием для группировки контента в репозитории microsoft-graph-docs служит язык статьи, а затем — ее тема. Файл README.md в корневой папке любого каталога раздела задает структуру статей внутри раздела.

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

Использование GitHub, Git и этого репозитория

Примечание. Большую часть сведений из этого раздела можно найти в статьях [справки GitHub][]. Если вы знакомы с Git и GitHub, переходите к разделу Дополнение и изменение содержимого, в котором представлены подробные сведения о работе с кодом и содержимым в этом репозитории.

Настройка вашего ответвления в репозитории

  1. Чтобы вносить изменения в этот проект, настройте учетную запись GitHub. Если вы еще не сделали этого, перейдите на [домашнюю страницу GitHub][] и зарегистрируйтесь.
  2. Настройте Git на своем компьютере. Выполните действия, указанные в руководстве по настройке Git.
  3. Создайте свое ответвление этого репозитория. Для этого нажмите кнопку Fork (Развилка) в верхней части страницы.
  4. Скопируйте свое ответвление на локальный компьютер. Для этого откройте GitBash. Введите в командной строке следующую команду:
git clone https://github.com/{your user name}/microsoft-graph-docs.git

Затем создайте ссылку на корневой репозиторий с помощью следующих команд:

cd microsoft-graph-docs
git remote add upstream https://github.com/microsoftgraph/microsoft-graph-docs.git
git fetch upstream

Поздравляем! Вы настроили свой репозиторий. Вам не потребуется повторять эти действия.

Добавление и редактирование содержимого

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

  1. Создайте новую ветвь.
  2. Добавьте или отредактируйте содержимое.
  3. Отправьте запрос на включение внесенных изменений в основной репозиторий.
  4. Удалите ветвь.

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

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

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

  1. Откройте GitBash.
  2. Введите в командной строке команду git pull upstream master:<new branch name>. При этом создается локальная ветвь, которая копируется из последней главной ветви microsoftgraph. Примечание. Для внутренних изменений замените идентификатор master в команде на нужную дату публикации.
  3. Введите в командной строке команду git push origin <new branch name>. Так вы сообщите GitHub о новой ветви. Новая ветвь появится в вашем ответвлении репозитория на сайте GitHub.
  4. Введите команду git checkout <new branch name>, чтобы переключиться на новую ветвь.

Добавление или редактирование содержимого

Вы можете перейти к репозиторию на локальном компьютере с помощью проводника. Файлы репозитория находятся в папке C:\Users\<yourusername>\microsoft-graph-docs.

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

Файлы в папке C:\Users\<yourusername>\microsoft-graph-docs — это рабочая копия новой ветви, которую вы создали в локальном репозитории. Изменение файлов в этой папке не влияет на локальный репозиторий, пока вы не примените это изменение. Чтобы применить изменение в локальном репозитории, введите следующие команды в GitBash:

git add .
git commit -v -a -m "<Describe the changes made in this commit>"

Команда add добавляет изменения в область промежуточного хранения для подготовки к их применению в репозитории. Точка после команды add указывает, что вы хотите поместить на промежуточное хранение все добавленные и измененные файлы, рекурсивно проверяя вложенные папки. (Если вы не хотите применять все изменения, вы можете добавить определенные файлы. Вы также можете отменить изменения. Для получения справки введите команду git add -help или git status.)

Команда commit применяет сохраненные изменения в репозитории. Параметр -m означает, что вы предоставляете комментарий к изменениям в командной строке. Если у вас нет конкретных сроков публикации, вы можете написать "опубликовать как можно скорее". Переключатели -v и -a указывать необязательно. Параметр -v включает подробные выходные данные команды, а параметр -a делает то, что вы уже сделали с помощью команды добавления.)

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

Отправка запроса на включение внесенных изменений в основной репозиторий

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

  1. Введите в командной строке GitBash команду git push origin <new branch name>. В локальном репозитории origin — это репозиторий GitHub, копией которого является ваш локальный репозиторий. Эта команда передает текущее состояние новой ветви, включая все изменения, внесенные на предыдущих этапах, в ваше ответвление GitHub.
  2. На сайте GitHub перейдите к новой ветви в своем ответвлении.
  3. Нажмите кнопку Pull Request (Запрос на включение внесенных изменений) в верхней части страницы.
  4. Убедитесь, что в качестве базовой ветви указана ветвь microsoftgraph/microsoft-graph-docs@master, а в качестве главной — <your username>/microsoft-graph-docs@<branch name>.
  5. Нажмите кнопку Update Commit Range (Обновить диапазон применения).
  6. Укажите название запроса и опишите изменения, которые вы вносите. Если вы исправили ошибку в элементе UserVoice или GitHub, обязательно сообщите об этом в описании.
  7. Отправьте запрос на включение внесенных изменений.

Его обработает один из администраторов сайта. Ваш запрос появится в репозитории microsoftgraph/microsoft-graph-docs site в разделе Issues (Проблемы). Когда запрос будет принят, проблема будет устранена.

Создание ветви после объединения

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

Допустим, локальная ветвь X была успешно объединена с главной ветвью microsoftgraph/microsoft-graph-docs, а вы хотите внести дополнительные изменения в объединенное содержимое. Создайте локальную ветвь X2, на основе главной ветви microsoftgraph/microsoft-graph-docs. Для этого откройте GitBash и выполните следующие команды:

cd microsoft-graph-docs
git pull upstream master:X2
git push origin X2

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

git checkout X2

После этого вы сможете проверить ее содержимое. Команда checkout обновляет все файлы в папке C:\Users\<yourusername>\microsoft-graph-docs до текущего состояния ветви X2. Получив новую ветвь для изменения, вы можете вносить изменения в содержимое и сохранять их в обычном порядке. Однако во избежание работы в объединенной ветви (X) рекомендуем удалить ее (см. раздел Удаление ветви ниже).

Удаление ветви

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

Чтобы удалить ветвь, сделайте следующее:

  1. Введите в командной строке GitBash команду git checkout master. Это гарантирует, что вы не работаете с удаляемой ветвью (это не допускается).
  2. Затем введите к командной строке команду git branch -d <branch name>. При этом ветвь будет удалена только на локальном компьютере, если она была успешно объединена с репозиторием верхнего уровня. (Вы можете изменить это поведение с помощью флага –D, но для начала убедитесь, что это необходимо.)
  3. Наконец, введите в командной строке команду git push origin :<branch name> (с пробелом перед двоеточием и без пробела после него). При этом ветвь будет удалена из вашего ответвления GitHub.

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

Как форматировать статью с помощью Markdown

Стандартные параметры Markdown

Во всех статьях в этом репозитории используется Markdown. Хотя на [домашней странице Markdown] [] можно найти полное введение (и полное описание синтаксиса), мы рассмотрим необходимые основные сведения.

Если вы ищете хороший редактор, попробуйте Markdown Pad.

Основы Markdown

Ниже представлен список наиболее распространенных операторов Markdown.

  • Разрывы строк и абзацы. В Markdown отсутствует элемент HTML <br />. Вместо этого новый абзац обозначается пустой строкой между двумя блоками текста.

  • Курсив. Элемент HTML <i>some text</i> записывается как *some text*.

  • Полужирный шрифт. Элемент HTML <strong>some text</strong> записывается как **some text**.

  • Заголовки. Заголовки HTML обозначаются определенным количеством символов # в начале строки. Количество символов # соответствует уровню заголовка в иерархии (например, # = h1, ## = h2 и ### = h3).

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

    1. Обратите внимание, что эта строка табулируется после знака точки.

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

  • Маркированные списки. Маркированные (неупорядоченные) списки почти идентичны упорядоченным спискам, но вместо обозначения 1. используется символ * , - или + . Несколько элементов списка создаются так же, как и в упорядоченных списках.

  • Ссылки. Базовый синтаксис для ссылки: [visible link text](link url). Для ссылок также могут быть предусмотрены сноски. Это описано в разделе Сноски для ссылок и изображений далее в этой статье.

  • Изображения. Базовый синтаксис для изображения: ![alt text for the image](image url). У изображений также могут быть сноски, которые рассматриваются в разделе Сноски для ссылок и изображений далее в этой статье.

  • Встроенный код HTML. Markdown позволяет встроить код HTML, но лучше не делать этого.

Сноски для ссылок и изображений

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

The image below is from [Google][googleweb]

![Google's logo][logo]

[googleweb]: http://www.google.com
[logo]: https://www.google.com/images/srpr/logo3w.png

Сгруппировав сноски в конце файла, вы можете легко находить, редактировать и повторно использовать URL-адреса ссылок и изображений.

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

  • Дополнительные сведения о Markdown см. на официальном сайте.
  • Дополнительные сведения об использовании Git и GitHub см. в [разделе справки GitHub] Справка GitHub, а при необходимости обратитесь к администраторам сайта.