Важно

Перевод - это работа сообщества : ссылка:Вы можете присоединиться. Эта страница в настоящее время переводится |прогресс перевода|.

3. Процесс разработки

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

3.1. Проект, основанный на git

За последние годы сложность исходного кода QGIS значительно возросла. Поэтому трудно предугадать побочные эффекты, которые повлечет за собой добавление той или иной функции. В прошлом у проекта QGIS были очень длинные циклы выпуска, поскольку восстановление стабильности программной системы после добавления новых функций требовало больших усилий. Чтобы преодолеть эти проблемы, QGIS перешел на модель разработки с использованием системы контроля версий git: новые функции сначала кодируются в контрибьюторских ветках и сливаются в QGIS master (основную ветку), когда они завершены и стабильны.

Исходный код QGIS размещен на сайте https://github.com/qgis/QGIS.

3.1.1. Роли

На GitHub существуют различные роли. При наличии аккаунта на GitHub вы уже имеете право вносить свой вклад, форкая репозиторий, и имеете роль «контрибьютор». Основные разработчики являются «коллабораторами» и могут сливать ветки в апстрим и официальный репозиторий.

3.1.2. Окружающая среда

Чтобы начать использовать и вносить вклад в репозиторий QGIS, вам необходимо:

  1. иметь аккаунт на GitHub <https://github.com/signup>`_

  2. создайте собственную копию QGIS-репозитория (см. fork)

  3. в вашей системе установлен git-клиент

  4. настройте ваше окружение <https://docs.github.com/en/get-started/getting-started-with-git/set-up-git>`_

  5. и получайте удовольствие!

3.1.3. Установка git

Проект git предоставляет последние версии программного обеспечения для большинства платформ. Следуйте инструкциям на сайте https://git-scm.com/downloads, чтобы получить и установить копию, соответствующую вашей ОС и архитектуре. Там же можно установить клиент git GUI для просмотра и управления вашими репозиториями (в большинстве случаев он установит git, если он еще не доступен).

3.2. Развитие в филиалах

3.2.1. Вклад в развитие

Зарегистрировавшись на GitHub и форкнув репозиторий, вы можете участвовать в проекте в качестве контрибьютора.

Примечание

Вносить вклад в код QGIS можно из вашего форк-репозитория на сайте GitHub. Новый код будет автоматически собран в тестовой среде. Но этот рабочий процесс может быстро обнаружить свои ограничения, если вы хотите внести сложные изменения. Инструкции ниже предполагают наличие локального клона.

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

  1. Клонируйте ваш репозиторий на локальный компьютер и настройте среду сборки

  2. Создайте новую ветку и внесите правки для разработки

  3. Зафиксируйте изменения и отправьте свою ветку обратно в удаленный форк на GitHub. Сразу после этого можно отправить запрос на создание ветки в виде веб-ссылки (URL).

  4. Откройте запрос на притяжение (PR) с просьбой притянуть коммит(ы) из вашей ветки в мастер-ветку в репозиторий upstream.

  5. Запускается процесс рецензирования, в ходе которого другие соавторы и соавторши получают информацию о вашем запросе. Вы должны реагировать на их комментарии и предложения.

Примечание

Более подробный рабочий процесс Github’s Fork & Pull Workflow доступен по адресу https://reflectoring.io/github-fork-and-pull/

Примечание

Большинство проектов QGIS (веб-сайт, документация, pyQGIS API, плагины…) доступны на странице GitHub <https://github.com/qgis>`_ и могут получить вклад, следуя тому же процессу.

3.2.2. Доступ к репозиторию

Чтобы иметь возможность взаимодействовать с локального диска как с удаленным форком, так и с репозиториями QGIS upstream, вам необходимо:

  1. Создайте клон своей копии на локальном диске

    cd path/to/store/the/repository
git clone https://github.com/<yourName>/QGIS.git

  2. Подключите основной репозиторий QGIS (мы назовем его upstream) к вашему

    git remote add upstream https://github.com/qgis/QGIS.git

  3. Проверка подключенных удаленных репозиториев

    git remote -v
# origin   https://github.com/<YourName>/QGIS.git (fetch)
# origin   https://github.com/<YourName>/QGIS.git (push)
# upstream https://github.com/qgis/QGIS.git (fetch)
# upstream https://github.com/qgis/QGIS.git (push)

    Теперь ваш онлайн-репозиторий доступен с локального диска, и вы можете взаимодействовать с ним, используя имя origin. Если вы хотите получить изменения из репозитория qgis/QGIS, используйте upstream.

Примечание

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

Смотрите файл : источник:INSTALL <INSTALL.md> в дереве исходных текстов для получения конкретных инструкций по сборке версий для разработки.

3.2.3. Процедура

  1. Первоначальное объявление в списке рассылки или репо проблем:

    Прежде чем приступать к работе, сделайте объявление в списке рассылки разработчиков, чтобы узнать, не работает ли другой разработчик над той же функцией. Вы также можете упомянуть о своем интересе в виде комментария в отчете о проблеме, если таковой существует в репозитории. Если новая функция требует каких-либо изменений в архитектуре QGIS, необходимо подготовить QGIS Enhancement Proposal (QEP).

  2. Создайте ветку в локальном репозитории:

    Создайте новую ветку git для разработки новой функции, основываясь на последнем состоянии мастер-ветки.

    git fetch upstream master
git checkout -b newfeature upstream/master
  3. Теперь вы можете приступить к разработке:

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

  4. Правильное форматирование, проверка орфографии и контроль качества кода

    Правильное форматирование, проверка орфографии и контроль качества кода осуществляются с помощью git-хука перед коммитом.

    Это можно автоматизировать с помощью запуска:

    pre-commit install

    Сценарий проверки орфографии можно запустить и самостоятельно:

    ./scripts/astyle_all.sh
  5. Зафиксируйте изменения в репозитории git:

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

    git add path/to/your/files
git commit -m "Add a comment describing your nice feature"

    Без опции -m откроется новое окно редактора, в котором вы сможете написать сообщение о фиксации.

    Вот некоторые рекомендации <https://www.conventionalcommits.org/en/v1.0.0/#summary>`_ по формату описания коммитов.

  6. Теперь вы можете захотеть поделиться своей работой с членами сообщества QGIS. Разместите свою новую функцию в онлайн-репозитории форков, сделав это:

    git push origin newfeature

    Примечание

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

  7. Представьте свои изменения с помощью pull-request

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

    Совет

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

  8. Регулярно обновляйтесь до мастера upstream:

    Рекомендуется регулярно выполнять ребазинг для включения изменений в master в ветку. Это облегчает последующее слияние ветки с мастером. После ребазинга вам нужно git push -f в ваше форкнутое репо.

    git pull --rebase upstream master
git push -f origin newfeature

Примечание

Информацию о том, как стать мастером GIT, можно найти на следующих сайтах.

3.2.4. Тестирование перед слиянием с мастером

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

3.3. Отправка запросов на выборку

Есть несколько рекомендаций, которые помогут вам легко вводить ваши исправления и запросы на исправления в QGIS, а нам - легко работать с исправлениями, которые нам присылают.

В целом, разработчикам будет проще, если вы будете отправлять запросы на вытягивание на GitHub. Здесь мы не описываем запросы, а отсылаем вас к документации по запросам на GitHub <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests>`_.

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

Pull-запросы вызывают различные проверки системы непрерывной интеграции (CI): сборку для различных окружений и запуск тестов, запуск лайнеров кода, проверки орфографии и т. д. Обязательно посмотрите на результаты этих проверок и постарайтесь решить проблемы, которые они поднимают. Конечно, вы можете задать вопрос в запросе на исправление, если вам нужна помощь других разработчиков для понимания и/или решения проблемы.

Если вы разработчик и хотите оценить очередь запросов на вытягивание, есть очень хороший инструмент, позволяющий сделать это из командной строки <https://changelog.com/posts/git-pulls-command-line-tool-for-github-pull-requests>`_

В целом, когда вы отправляете PR, вы должны взять на себя ответственность за то, чтобы довести его до конца - отвечать на запросы других разработчиков, искать «чемпиона» для вашей функции и время от времени мягко напоминать им, если вы видите, что ваш PR не выполняется. Пожалуйста, имейте в виду, что проект QGIS осуществляется на добровольных началах, и люди не смогут мгновенно отреагировать на ваш PR. Мы проверяем поступающие запросы на исправление, но иногда мы что-то пропускаем. Не обижайтесь и не расстраивайтесь. Попробуйте найти разработчика, который сможет вам помочь, и свяжитесь с ним, спросив, может ли он посмотреть на ваш патч. Если вы считаете, что PR не получает того внимания, которого заслуживает, вы можете ускорить его (в порядке приоритета):

  • Помогайте просматривать чужие запросы, чтобы освободить человека, назначенного на ваш.

  • Отправьте сообщение в список рассылки, «рекламируя» свой PR и рассказывая о том, как замечательно будет включить его в кодовую базу.

  • Отправьте сообщение человеку, которому был назначен ваш PR в очереди PR.

  • Отправьте сообщение руководящему комитету проекта с просьбой помочь включить ваш PR в кодовую базу.

3.3.1. Лучшая практика создания запроса на притяжение

  • Всегда начинайте ветку фич с текущего мастера.

  • Если вы кодируете ветку фич, не «сливайте» ничего в эту ветку, а лучше сделайте ребазинг, как описано в следующем пункте, чтобы сохранить историю чистой.

  • Перед созданием запроса на притяжение выполните git fetch upstream и git rebase upstream/master (если upstream - это удаленный доступ для пользователя qgis, а не ваш собственный, проверьте ваш .git/config или выполните git remote -v | grep github.com/qgis).

  • Вы можете неоднократно выполнять git rebase, как в последней строке, без какого-либо ущерба (при условии, что единственной целью вашей ветки является слияние с master).

  • Внимание: После ребаза вам нужно git push -f в вашем форкнутом репозитории. ** РАЗРАБОТЧИКИ ЯДРА: НЕ ДЕЛАЙТЕ ЭТОГО В ПУБЛИЧНОМ РЕПОЗИТОРИИ QGIS!**

3.3.2. Специальные ярлыки для уведомления документаторов

Существует специальная метка (Необходима документация), которую рецензенты могут присвоить вашему запросу, чтобы автоматически генерировать отчеты о проблемах в репозитории QGIS-Documentation, как только ваш запрос будет объединен. Не забудьте упомянуть, заслуживает ли ваша функция такой метки.

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

  • [needs-docs] для указания авторам доков на необходимость добавления дополнительной документации после исправления или добавления к уже существующей функциональности.

  • [feature] в случае новой функциональности. Хорошим началом будет заполнение хорошего описания в вашем PR.

Пожалуйста, разработчики используют эти метки (без учета регистра), чтобы у составителей документации были проблемы, над которыми нужно работать, и обзор того, что нужно сделать. НО также, пожалуйста, найдите время добавить текст: либо в коммит, либо в саму документацию.

3.3.3. Должная осмотрительность

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

3.4. Критерии слияния Pull Requests

Пожалуйста, смотрите QEP 323 - Политика подачи и слияния изменений для текущей политики в отношении приемлемой подачи запросов на слияние.

3.5. Получение доступа к записи в GIT

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

Примечание

После перехода на GIT мы стали реже предоставлять доступ на запись новым разработчикам, поскольку обмен кодом в github осуществляется просто - с помощью форка QGIS и последующей отправки запросов на вытягивание.

Всегда проверяйте, что все компилируется, прежде чем делать какие-либо коммиты / запросы на исправление. Старайтесь быть в курсе возможных поломок, которые ваши коммиты могут вызвать у людей, собирающих на других платформах и со старыми/новыми версиями библиотек.