Внесение вклада в проект#

Этот документ предоставляет руководство по тому, как внести вклад в проект. Для краткости далее Pull Request сокращен до «PR».

В общих чертах процесс состоит из следующих этапов:

  1. Создание Issue.

  2. Создание форка репозитория.

  3. Клонирование форка на локальный компьютер.

  4. Создание рабочей ветки.

  5. Внесение изменений.

  6. Фиксация изменений.

  7. Выталкивание изменений на GitHub.

  8. Прохождение автоматической проверки качества кода.

  9. Оформление PR в основной репозиторий проекта.

  10. Слияние PR с веткой master.

Далее каждый шаг рассматривается более подробно.

Создание Issue#

Чтобы предложить изменение, оформите его как Issue в репозитории проекта. Для этого:

  1. Перейдите в раздел Issues.

  2. Нажмите кнопку New issue.

  3. В поле Title введите краткое описание изменения.

  4. В поле Add a decription опишите изменение более развёрнуто.

  5. Нажмите кнопку Submit new issue.

Общие правила создания Issue

  • Перед созданием Issue убедитесь, что такого же или похожего Issue ещё нет.

  • Не создавайте Issue, требующего переработки сразу нескольких разделов сайта. Лучше создайте несколько отдельных Issue.

    Помните, что «быстро – это медленно без остановок».

  • Не создавайте отдельные Issue на каждую опечатку.

Создание форка репозитория#

Создайте форк репозитория – собственную копию, с которой будете работать.

  1. Перейдите на страницу проекта на GitHub.

  2. Нажмите кнопку Fork.

  3. Не изменяя настроек по умолчанию, нажмите кнопку Create fork.

В вашем профиле GitHub будет создан форк репозитория.

Клонирование форка репозитория#

Attention

Для клонирования репозитория используйте ветку develop!

Клонируйте форк из своего профиля GitHub на локальный компьютер:

  1. На странице репозитория нажмите кнопку Code.

  2. В открывшейся панели на вкладке Local выберите вкладку SSH.

  3. Скопируйте путь к репозиторию в буфер обмена.

  4. Запустите эмулятор терминала и выполните команду клонирования репозитория с GitHub на локальный компьютер:

    git clone ssh://git@github.com:<profile>/techwritersru.git

    где <profile> – название вашего профиля на GitHub.

  5. Добавьте в список источников основной репозиторий проекта:

    git remote add upstream ssh://git@github.com:techwri/techwritersru.git

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

Создание рабочей ветки#

Attention

Вносить изменения напрямую в ветки master и develop запрещено!

  1. Перейдите в каталог репозитория:

    cd techwritersru/

  2. Переключитесь на ветку develop:

    git checkout develop

  3. Получите самую свежую версию кода из upstream:

    git pull develop upstream

  4. Создайте новую ветку:

    git checkout -b <type>/issue-<issue>-<description>

    где:

    • <type> – тип нововведения:

      • bugfix – исправление ошибки;

      • feature – новый контент.

    • <issue> – номер Issue в основном репозитории проекта.

    • <description> – краткое описание изменений на английском языке.

Внесение изменений#

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

Соблюдайте следующие правила:

  • Не выходите за рамки задачи, описанной в Issue.

  • Не оставляйте висячих пробелов.

  • Не используйте средства автоматического форматирования, если они изменяют строки, не имеющие отношения к Issue.

    Это значительно увеличивает объём изменений, которые должен проверить ревьюер. Мы оставляем за собой право отклонять такие PR без объяснения причин.

Фиксация изменений#

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

    Это можно сделать различными способами, например, в виртуальном окружении Python или с помощью Docker-контейнера. В любом случае, сайт должен собираться без ошибок и предупреждений.

  2. Добавьте изменения в индекс:

    git add .

  3. Зафиксируйте изменения:

    git commit -m "ISSUE-<issue> <description>"

    где:

    • <issue> – номер Issue в основном репозитории проекта;

    • <description> – краткое описание сделанных изменений на английском языке.

      Note

      • Общая длина комментария не должна превышать 80 знаков.

      • Описание изменений должно отвечать на вопрос «Что сделают эти изменения?»

Выталкивание изменений на GitHub#

Вытолкните (push) изменения на GitHub:

git push origin --set-upstream <branch>

где <branch>> – название созданной ранее ветки.

Прохождение автоматической проверки качества кода#

  1. Перейдите на страницу форка в своем профиле GitHub и выберите вкладку Pull requests.

  2. Нажмите кнопку New pull request.

  3. На странице Comparing changes:

    1. В поле base repository выберите свой форк репозитория.

    2. В поле base выберите как целевую ветку develop.

    3. Нажмите кнопку Create pull request.

  4. Заполните форму Open a pull request:

    • Add a title – введите краткое описание сделанных изменений.

    • Add a description – введите более подробное описание сделанных изменений. В конце сообщения для связи PR с Issue добавьте строку:

      #<issue>

      где <issue> – номер Issue в основном репозитории проекта.

  5. Нажмите кнопку Create pull request.

  6. Перейдите во вкладку Actions.

    Для нового PR будет запущен процесс автоматической сборки и тестирования. Подробности см. в разделе CI/CD.

  7. Дождитесь завершения Workflow, запущенного после создания PR.

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

Оформление PR в основной репозиторий проекта#

  1. Если автоматическая проверка качества кода прошла успешна, перенаправьте созданный ранее PR в ветку develop основного репозитория проекта.

  2. Дождитесь реакции контрибьюторов.

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

Note

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

Слияние PR с веткой develop#

Когда PR будет готов к слиянию с develop, кто-то из контрибьюторов сделает слияние и закроет связанный Issue. В этом случае выполните следующие действия:

  1. Переключитесь на ветку develop:

    git checkout develop

  2. Получите актуальную ревизию кода из upstream:

    git pull develop upstream

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

    git branch -D <branch>

  4. Перейдите на страницу форка на GitHub и удалите копию рабочей ветки из него.

Инструкции для администратора#

Краткие инструкции для администраторов проекта.

Как принимать изменения (Pull requests) из других веток#

Для принятия PR на GitHub выполните следующие шаги:

  1. Откройте страницу проекта на GitHub.

  2. Перейдите во вкладку Pull Requests.

  3. Найдите нужный PR в списке открытых PR.

  4. Нажмите на заголовок PR, чтобы открыть его страницу.

  5. Убедитесь, что автоматическая проверка кода успешно пройдена.

  6. Убедитесь, что PR:

    • содержит только изменения, описанные в связанном Issue;

    • не содержит изменений, не имеющих отношения к Issue.

  7. При необходимости оставьте комментарии и верните PR на доработку.

  8. Если PR не требует доработки, либо все нужные правки уже сделаны, нажмите кнопку Merge.

  9. Выберите тип слияния Squash and merge.

  10. Нажмите кнопку Confirm merge, чтобы выполнить слияние.