Участие в разработке документацииContribute to the docs

Примечание. Для участия в составлении документации необходимо иметь учетную запись GitHub.Note: In order to contribute, you must have a GitHub account.

Редактирование существующего документаEdit an existing doc

  1. Найдите документ, который следует отредактировать.Find the doc you'd like to edit.

  2. Выберите Contribute to this topic (Изменить этот раздел).Select Contribute to this topic

Вы будете автоматически перенаправлены в GitHub в файл разметки, связанный с этим файлом.This will automatically redirect you to the markdown file in GitHub associated with this file.

Убедитесь, что вы вошли в GitHub.Make sure you are signed into GitHub. В противном случае выполните вход или создайте учетную запись GitHub.If not, either sign in or create a GitHub account.

  1. Выберите значок правки для редактирования в редакторе браузера.Select the edit icon to edit with the in browser editor.

  1. Внесите соответствующие изменения.Make changes inline.

Возможные действия:Possible actions:

  1. Изменение файлаEdit file
  2. Просмотр измененийPreview changes
  3. Переименование файла (крайне маловероятно, что это потребуется)Rename the file (it's very unlikely you'll want to do this)

  1. Предложить изменения в виде запроса на включениеPropose your changes as a pull request

  1. Проверить измененияReview your changes

Что проверяется в запросе на включениеWhat we're looking for in a pull request

  • Изменение верно— достоверно представляет технологиюThe change is correct -- it accurately represents the technology
  • Правильная орфография и грамматикаSpelling/grammar are correct
  • Логическое расположение в документацииLogical location in the documentation

  1. Создание запроса на включение внесенных измененийCreate a pull request

Запрос на включениеPull requests

Большинство изменений будут внесены по запросу на включение.Most changes will be committed via pull request. Запрос на включение— способ проверки набора изменений несколькими рецензентами, а также изменения и комментирования текущего содержимого.A pull request is a way of reviewing a change set with multiple reviewers, changing, and commenting on the current content.

Разветвление репозитория и локальное редактированиеFork the repo and edit locally

Для длительной работы с документами клонируйте репозиторий в локальную среду и пользуйтесь им на своем компьютере.For long term doc work Clone the repository locally and work on your machine.

Следующее руководство описывает, как эмулировать мою настройку (автор— Сара Кули (Sarah Cooley)).The following guide shows you how to emulate my (Sarah Cooley's) set up. Существует множество альтернативных настроек, которые работают одинаково хорошо.There are many alternative setups that work equally well.

Примечание. Все эти средства для работы с документами функционируют одинаково хорошо на Linux или OSX.Note: All of these doc tools work equally well on Linux/OSX. Если вам нужны другие руководства, запросите их.If you want other guides, ask.

Процедура делится на три этапа:This is broken into three sections:

Настройка GitSet up Git

  1. Установите Git (в Windows) отсюдаInstall git (on Windows) from here

В установке нужно изменить всего одно значение:There is only one value in the installation you need to change:

Настройка среды PATH. Используйте Git из командной строки Windows.Adjusting your PATH environment Use Git from the Windows Command Prompt

Это позволяет использовать команды Git в консоли PowerShell или в любой консоли Windows.This lets you use git commands in the PowerShell console/in any Windows console.

  1. Настройте свое удостоверение Git.Configure your git identity

Откройте окно PowerShell и выполните следующую команду:Open a PowerShell Window and run:

git config --global user.name "User Name"
git config --global user.email username@microsoft.com

Git использует эти значения для обозначения фиксаций.Git uses these values to label your commits.

Если возникает приведенная ниже ошибка, возможно, Git установлен неправильно или необходимо перезапустить PowerShell.If recieved the following error git probably isn't installed properly or you need to relaunch PowerShell. PowerShell git : The term 'git' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.

  1. Настройте свою среду Git.Configure your git environment

    Настройте вспомогательное средство для учетных данных, чтобы ввести имя пользователя и пароль только один раз (по крайней мере на этом компьютере).Set up a credential helper so you only need to enter username and password once (at least on this machine). Я использую это простое вспомогательное средство для учетных данных WindowsI use this basic Windows cred helper

    После установки выполните следующую команду, чтобы включить вспомогательное средство для учетных данных и задать поведение принудительной отправки:Once that is installed, run the following to enable the credential helper and set your push behavior:

    git config --global credential.helper manager
    git config --global push.default simple
    

    При первом запуске необходимо выполнить проверку подлинности для GitHub— вам будет предложено ввести свое имя пользователя и код двухфакторной проверки подлинности, если он используется.The first time you need to authenticate against GitHub - you will be prompted for your username, and the two-factor authcode if you have it enabled. Пример.Example:

    C:\Users\plang\Source\Repos\Virtualization-Documentation [master]> git pull
    Please enter your GitHub credentials for https://github.com/
    username: plang@microsoft.com
    password:
    authcode (app): 562689
    

    При этом автоматически создается личный маркер доступа с соответствующими разрешениями на GitHub; сохраните его в защищенном расположении на локальном компьютере.This will automatically a Personal Access Token with the right permissions on GitHub, then store that token securely on the local machine. Больше этот запрос выводиться не должен.You shouldn't be prompted again in the future.

  2. Выполните разветвление репозитория.Fork the repository

  3. Клонируйте репозиторий.Clone the repository

Клон Git создает локальную копию репозитория с подходящими обработчиками для синхронизации с другими клонами того же репозитория.Git clone makes a local copy of the git repository with the right hooks to sync with other clones of the same repository.

По умолчанию клон создает в текущем каталоге папку, имя которой совпадает с именем репозитория.By default, clone will create a folder with the same name as the repository in the current directory. Я храню все репозитории Git в своем каталоге пользователя.I keep all of my git repos in my user directory. Дополнительные сведения о клонировании в Git см. здесь.Read more about git clone here.

cd ~
git clone https://github.com/Microsoft/Virtualization-Documentation.git

Если процедура будет успешно выполнена, появится папка Virtualization-Documentation.If successful, you now have a Virtualization-Documentation folder.

cd Virtualization-Documentation
  1. [Необязательно] Настройте Posh-Git.[Optional] Set up Posh-Git

Posh-Git— это модуль PowerShell, который создан членами сообщества и делает работу с Git в PowerShell немного удобнее.Posh-Git is a community created PowerShell module that makes using Git in PowerShell a little friendlier. Он добавляет заполнение нажатием клавиши в Git для PowerShell, а также отображение сведений о ветвлении и состоянии файла в командной строке.It adds tab completion for Git in PowerShell, and can also make your prompt display useful about branching and file state. Дополнительные сведения о нем см. здесь.Read more about it here. Posh-Git можно установить, выполнив приведенную ниже команду в консоли администратора PowerShell.You can install Posh-Git by running the following in an Administrator PowerShell console.

Install-Module -Name posh-git

Чтобы автоматически запускать Posh-Git при каждом открытии PowerShell, добавьте следующий код в свой профиль PowerShell (например, %UserProfile%\My Documents\WindowsPowerShell\profile.ps1 ).To make Posh-Git work automatically each time you start PowerShell, add the following code to your PowerShell Profile (e.g. %UserProfile%\My Documents\WindowsPowerShell\profile.ps1 )

Import-Module posh-git

function global:prompt {
  $realLASTEXITCODE = $LASTEXITCODE

  Write-Host($pwd.ProviderPath) -nonewline

  Write-VcsStatus

  $global:LASTEXITCODE = $realLASTEXITCODE
  return "> "
}

Проверка и задание учетных данныхValidate and stash credentials

Чтобы проверить, правильно ли настроен репозиторий, попробуйте извлечь новое содержимое.To validate that the repository is set up correctly, try pulling new content.

git pull

Настройка среды редактирования разметкиSet up markdown editing environment

  1. Скачайте VSCode.Download VSCode

  2. Выполните тестовую фиксацию.Make a test commit. Если учетные данные заданы правильно, все должно работать как нужно.If your credentials are stashed correctly, it should all work perfectly.