📁 Настраиваем Git для правильной работы с опенсорс-проектами

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

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

Форк-проект

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

Клонируйте ваш форк

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

git clone git@github.com:rnjudge/tern.git
cd tern

2. Настройка веток/окружения

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

Добавьте удаленный upstream-репозиторий

Удаленный репозиторий – это репозиторий Git, размещенный где-то в интернете. Когда вы клонируете свой форк проекта, вы создаете локальную копию вашего форка удаленного репозитория. Когда вы запускаете git clone (git clone), Git автоматически присваивает вашему удаленному репозиторию имя origin. Вы можете составить список своих удаленных хранилищ с помощью команды git remote. После выполнения вышеприведенной команды clone вы должны увидеть в списке ваше удаленное хранилище origin:

$ git remote -v
origin    git@github.com:rnjudge/tern.git (fetch)
origin    git@github.com:rnjudge/tern.git (push)

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

Если у вас настроен SSH-ключ, запустите его:

$ git remote add upstream git@github.com:tern-tools/tern.git

В противном случае добавьте пульт, используя https:

$ git remote add upstream https://github.com/tern-tools/tern.git

Создайте «домашнюю базовую» ветвь для отслеживания изменений в основном проекте

«Домашняя базовая ветка» – это не технический термин Git или GitHub, а фраза, которую я использую для описания ветки, которую мы будем использовать для отслеживания изменений в репозитории, что поможет нам легко переделывать наши PR в будущем. Это означает, что вы не будете использовать свою домашнюю базовую ветку для разработки или внесения изменений в исходный код. Скорее, вы будете использовать её для перебазирования веток разработки и создания из неё новых рабочих веток. Ветка up помогает вам легко синхронизироваться с репозиторием upstream.

В этом примере моя домашняя базовая ветка называется up (но вы можете назвать ее как угодно). Другие ваши ветви разработки также будут основаны на этой ветви up. В следующем наборе команд главная ветвь Tern будет называться main. В некоторых репозиториях она может называться master, поэтому вам, возможно, придется отредактировать команды соответствующим образом. Выполните эти команды, чтобы настроить вашу ветку up для отслеживания изменений в репозитории проекта upstream:

$ git fetch upstream
$ git checkout -b up upstream/main
$ git push origin up:refs/heads/main

Обратите внимание, что вам нужно будет настроить ветку up только один раз.

3. Общий рабочий процесс (workflow)

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

Создайте рабочую ветвь

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

Во-первых, убедитесь, что ветка up является текущей.

$ git checkout up
$ git pull --rebase

Затем создайте и переключитесь на свою рабочую ветку.

$ git checkout -b working_branch_name

Рабочая ветвь может быть названа так, как вы захотите.

Внесите и зафиксируйте (commit) изменения

Любые изменения, которые вы вносите в исходный код проекта, будут связаны с рабочей веткой, на которой вы находитесь (чтобы узнать, на какой ветке вы находитесь, выполните команду git checkout и посмотрите на звездочку). Когда вы посчитаете, что ваших изменений достаточно и они готовы к отправке в upstream-проект, вам сначала нужно добавить файлы для подготовки. Подготовка изменённых файлов для коммита – это способ сообщить Git'у, что файлы готовы быть зафиксированы. Для этого выполните:

$ git add <file/directory>

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

Зафиксируйте поэтапные изменения

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

$ git commit -s

Важное замечание: я не рекомендую использовать опцию -m с опцией git commit. git commit -m<msg> позволяет вам использовать заданное <msg> в качестве сообщения коммита в то же время, когда вы фиксируете изменения в коде. Однако это не позволяет писать подробные или грамотно оформленные сообщения о фиксации, поскольку сообщения коммита при использовании опции -m обычно представляют собой короткие однострочные фразы. Я выступала на конференции All Things Open и рассказывала о том, зачем и как писать хорошие сообщения коммита (этот доклад также был преобразован в blog форму). Многие проекты с открытым исходным кодом также имеют требования к сообщениям коммита для проекта. Перед началом работы обязательно ознакомьтесь с ними. Как только вы закончите писать сообщение коммита, сохраните его и выйдите из окна сообщения.

Внесите свои изменения

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

$ git push origin <working_branch_name>

Открытие пулл-реквеста

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

4. Редактирование своего коммита после того, как вы уже открыли PR

Перезалейте свои изменения в upstream

Если вас просят внести изменения в ваш PR, возможно, что с момента отправки изменений в репозиторий upstream были слиты другие коммиты. Чтобы быть уверенным, что вы не загружаете устаревший код или файлы при обновлении вашего PR, лучше всего перебазировать ваши изменения в удаленный репозиторий upstream. Чтобы сделать это легко, используйте домашнюю базовую ветку. Имейте в виду, что домашняя базовая ветвь названа up для этого примера, но вы можете назвать ее по-другому.

Следующий набор команд сначала позволит получить все изменения из upstream, а затем применить их к вашей ветке up. Это означает, что вы обновите свою ветвь up, чтобы она соответствовала последним изменениям в репозитории, в который вы отправляете свой PR. После того как вы переключитесь обратно на свою рабочую ветвь, команда git rebase up обновит вашу рабочую ветвь (содержащую изменения вашего PR), чтобы она включала в себя последние изменения из репозитория (через ветвь up), сохраняя при этом изменения, сделанные вами в рабочей ветви. Этот процесс позволяет вам получить изменения из репозитория upstream, чтобы ваш PR мог быть объединен с данным репозиторием без конфликтов. Это также гарантирует, что все тесты непрерывной интеграции, запускаемые после обновления или отправки вашего PR, будут работать с последними изменениями в кодовой базе.

$ git checkout up
$ git pull --rebase
$ git checkout <existing_pr_working_branch_name>
$ git rebase up

Теперь, когда ваша рабочая ветвь актуальна, вы можете вносить свои изменения. Чтобы внести изменения в файлы исходного кода, вы должны отредактировать файл(ы) и запустить git add, чтобы подготовить их для коммита, как вы это делали раньше. Чтобы обновить ваш PR для добавления этих изменения, вы можете внести правки в предыдущий коммит. Внесение изменений в ваш коммит также даст вам возможность отредактировать сообщение коммита, если вам это необходимо. Если вам нужно внести изменения только в сообщение коммита, а не в файлы исходного кода, пропустите git add и просто выполните:

$ git commit --amend

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

Ре-пуш изменений

Убедитесь, что вы всё ещё находитесь на рабочей ветке, где вы только что внесли изменения в свой коммит. Внесение изменений в локальный коммит не обновляет коммит в удаленном репозитории и не изменяет пулл-реквест. Чтобы обновить свой PR, вам нужно будет повторно отправить изменения в форк удаленного репозитория:

$ git push -f origin <existing_pr_working_branch_name>

Опция -f/force push может быть опасной при неправильном использовании, так как она может переписать историю коммитов в удаленном репозитории вашей собственной локальной истории. Однако в данном случае она необходима, поскольку вы вносите изменения в старый коммит и намеренно переписываете историю git в вашем форке, чтобы включить в неё свои последние правки. Когда вы выполняете принудительный push после внесения изменений в свой коммит, вы создаёте новый git commit ID, чтобы связать его с вашими изменениями.

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

Продолжая вносить свой вклад

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

Материалы по теме

• 🔥 Как креативно оформить профиль на GitHub, чтобы он привлекал внимание
• 💽 Git для Data Science: контроль версий моделей и датасетов с помощью DVC
  
• 👍 Как правильно писать сообщения коммитов в GIT, чтобы всем было хорошо
  
• 😻 7 проектов на GitHub, которые необходимы каждому JavaScript-разработчику

Источники

• https://github.com/readme/guides/configure-git-environment