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

В статье предполагается, что вы уже клонировали репозиторий документации локально, и вы будете вносить изменения на локальном компьютере, а не на GitHub или в пространстве кода. Дополнительные сведения см. в разделе [Клонирование репозитория](/ru/repositories/creating-and-managing-repositories/cloning-a-repository?tool=webui).

## Настройка ветви раздела и внесение изменений

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

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

   ```shell
   cd ~/my-cloned-repos/docs
   ```

2. Переключитесь на ветвь по умолчанию: `main`

   ```shell
   git checkout main
   ```

3. Получение последних фиксаций из удаленный репозиторий.

   ```shell
   git pull origin main
   ```

4. Перейдите к разделу или создайте ветвь раздела.
   * Чтобы запустить новый проект, создайте ветвь раздела из `main`.

     ```shell
     git checkout -b YOUR-TOPIC-BRANCH
     ```

     > \[!NOTE]
     > Вы можете использовать косую черту в составе имени ветви, например, чтобы включить имя пользователя:
     >
     > ```shell
     > git checkout -b my-username/new-codespace-policy
     > ```

   * Чтобы работать с существующим проектом, перейдите в ветвь раздела и выполните слияние изменений `main`.

     ```shell
     git checkout YOUR-TOPIC-BRANCH
     git merge main
     ```

     Если вы работаете с конфликт слияния, выполните действия, описанные далее в этой статье для [разрешения конфликт слияния.](#resolving-merge-conflicts)

5. Откройте предпочитаемый текстовый редактор, измените файлы по мере необходимости, а затем сохраните изменения.

## Фиксация и отправка изменений

1. Когда вы будете готовы зафиксировать изменения, откройте терминал и проверьте состояние ветви раздела.`git status` Убедитесь, что вы видите правильный набор изменений.

   ```shell
   git status
   On branch YOUR-TOPIC-BRANCH

   Changes not staged for commit:
     (use "git add <file>..." to update what will be committed)
     (use "git checkout -- <file>..." to discard changes in working directory)
           deleted:    example-deleted-file.md
           modified:   example-changed-file.md

   Untracked files:
     (use "git add <file>..." to include in what will be committed)
           example-new-file.md
   ```

2. Выполните этап измененных файлов, чтобы они были готовы к фиксации в ветви раздела.

   * Если вы создали новые файлы или обновили существующие файлы, используйте `git add FILENAME [FILENAME...]`. Например:

     ```shell
     git add example-new-file.md example-changed-file.md
     ```

     Это добавляет обновленную версию файлов в промежуточную область Git, из которой можно зафиксировать изменения. Чтобы отменить метку файла, используйте `git reset HEAD FILENAME`. Например, `git reset HEAD example-changed-file.md`.

   * При удалении файлов используйте `git rm FILENAME [FILENAME...]`. Например:

     ```shell
     git rm example-deleted-file.md
     ```

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

   ```shell
   git commit -m "Commit message title (max 72 characters)

   Optional fuller description of what changed (no character limit).
   Note the empty line between the title and the description,
   and the closing quotation mark at the end of the commit message."
   ```

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

   Чтобы удалить эту фиксацию, используйте `git reset --soft HEAD~1`. После выполнения этой команды изменения больше не фиксируются, но измененные файлы остаются в промежуточной области. Вы можете внести дальнейшие изменения, а затем `add` и `commit` снова.

4. Отправьте изменения в удаленный репозиторий на GitHub.

   * При первом отправке ветви можно добавить ветвь вышестоящего отслеживания. Это позволяет использовать `git pull` и `git push` в этой ветви без дополнительных аргументов.

     ```shell
     git push --set-upstream origin YOUR-TOPIC-BRANCH
     ```

   * Если вы выполнили отправку этой ветви раньше и настроили ветвь отслеживания вышестоящего потока, которую можно использовать:

     ```shell
     git push
     ```

### Рекомендации по фиксациям

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

* Если вы включаете отзывы или хотите обратиться к набору изменений для конкретного человека или команды для проверки, пользователь, @mention чьи предложения вы включаете. Например: "Включение обратной связи от @octocat", или "Обновление действий по настройке выставления счетов — cc @monalisa для точности".

* Если фиксация устраняет проблему, можно указать номер проблемы в фиксации, а ссылка на фиксацию появится на временной шкале беседы о проблеме: "Адреса #1234 — добавляет шаги по резервному копированию виртуальной машины перед обновлением".

  > \[!NOTE]
  > Как правило, мы не закрываем проблему с помощью фиксации. Чтобы закрыть проблему, откройте запрос на вытягивание и добавьте "Закрыть #1234" в описание. Связанная проблема будет закрыта при слиянии запроса на вытягивание. Дополнительные сведения см. в разделе [Связывание запроса на вытягивание с проблемой](/ru/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue).

* Сделать сообщения фиксации понятными, подробными и императивными. Например: "Добавить концептуальную статью о 2FA", а не "Добавить информацию".

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

* После выполнения нескольких фиксаций только до GitHub. Pushing после каждой фиксации добавляет шум к нашим каналам ops в Slack и приводит к ненужным сборкам для выполнения.

## Разрешение конфликтов слияния

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

Существует два способа обработки конфликт слияния:

* Измените файл в текстовом редакторе и выберите, какие изменения следует сохранить. Затем зафиксируйте обновленный файл в ветви раздела из командной строки.
* [Разрешение конфликта слияния в GitHub](/ru/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github).

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

1. В командной строке обратите внимание на файлы, содержащие конфликт слияния.

2. Откройте первый из этих файлов в текстовом редакторе.

3. В файле найдите маркеры конфликт слияния.

   ```text
    <<<<<<< HEAD
    Here are the changes you've made.
    =====================
    Here are the changes from the main branch.
    >>>>>>> main
   ```

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

   ```text
   Here are the changes you want to use.
   ```

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

   > \[!NOTE]
   > При разрешении конфликт слияния следует применять осторожность. Иногда вы просто принимаете собственные изменения, иногда вы будете использовать изменения вышестоящего потока из `main` ветви, а иногда будете объединять оба набора изменений. Если вы не уверены в лучшем разрешении, будьте осторожны замены изменений из вышестоящей части, так как они, возможно, были сделаны по определенным причинам, о которых вы не знаете.

5. В терминале этап файла или файлов, которые вы только что изменили.

   ```shell
   git add changed-file-1.md changed-file-2.md
   ```

6. Зафиксируйте файлы.

   ```shell
   git commit -m "Resolves merge conflicts"
   ```

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

   ```shell
   git push
   ```

## Создание запроса на включение изменений

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

> \[!NOTE]
> Вы можете быстро получить доступ к запросам на вытягивание, созданные, щелкнув **запросы** на вытягивание в верхней части каждой страницы на GitHub.

Дополнительные сведения см. в разделе [Создание запроса на включение изменений](/ru/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request?tool=webui#creating-the-pull-request).