Рабочий процесс разработки#

Примечание: рассмотрите возможность наблюдения Рабочий процесс разработки SciPy до или после чтения, чтобы увидеть пример исправления ошибки и отправки pull request.

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

  1. В терминале представьтесь Git:

    git config --global user.email you@yourdomain.com
git config --global user.name "Your Name"

    Эта информация указывает на вашу работу, но обратите внимание, что она станет общедоступной, если вы "отправите" свою работу в GitHub. См. Настройка адреса электронной почты для коммитов в Git для получения дополнительной информации.

  2. Перейдите в корневую директорию вашего локального репозитория SciPy и введите:

    git remote add upstream https://github.com/scipy/scipy.git

    Это связывает имя upstream с официальным репозиторием SciPy расположенным на scipy/scipy.git. Обратите внимание, что когда вы клонировали свою форк репозитория SciPy, Git уже связал имя origin с вашим форком. Причина, по которой вам нужны оба этих “удалённые репозитории” заключается в том, что вы обычно начнете с последней версии SciPy из официального репозитория upstream, внести изменения, “отправить” ваши изменения в ваш форк репозитория origin, а затем отправить «pull request», запрашивая у SciPy «вытянуть» ваши изменения из вашего форка в официальный репозиторий.

  3. Инициализация git submodules:

    git submodule update --init

    Это извлекает и обновляет любые подмодули, которые нужны SciPy (такие как Boost).

Базовый рабочий процесс#

Короче говоря:

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

  2. Взламывайте! См. ниже.

  3. По завершении:

    • Участники: отправьте вашу ветку функций в ваш собственный репозиторий Github, и создать pull request.

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

Такой способ работы помогает сохранять работу хорошо организованной и историю как можно более ясной.

Смотрите также

Существует множество онлайн-руководств, которые помогут вам изучить git. Для обсуждения конкретных рабочих процессов git см. эти обсуждения на рабочий процесс git в linux, и рабочий процесс git ipython.

Создание новой ветки функций#

Сначала перейдите в корневую директорию SciPy в терминале и загрузите новые коммиты из upstream репозиторий:

git fetch upstream

Затем создайте новую ветку на основе основной ветки репозитория upstream:

git checkout -b my-new-feature upstream/main

Эквивалентно, вы можете поддерживать основную ветку своего репозитория в актуальном состоянии и создать новую ветку на её основе:

git checkout main
git rebase upstream/main
git checkout -b my-new-feature

По порядку эти команды

  1. обеспечить, чтобы main ветка вашего локального репозитория извлечена,

  2. применить все последние изменения из upstream/main (основной репозиторий SciPy, ветка main) в локальную main ветка, и

  3. создать и переключиться на новую ветку (-b) на основе вашего локального main ветка.

В любом случае важно, чтобы ваша ветка функций включала последние изменения из основного upstream, чтобы помочь избежать : DOC, BUG: Уточнить и обеспечить типы входных данных для объектов 'Data' когда приходит время отправить pull request.

Также рекомендуется собрать эту ветку и запустить тесты перед продолжением. Предполагая, что вы следовали одному из Сборка из исходного кода страницы для настройки вашей среды разработки, вам нужно активировать среду разработки и затем запустить тесты (обратите внимание, что dev.py test команда автоматически выполнит сборку, если это необходимо):

conda activate scipy-dev
python dev.py test -v

Рабочий процесс редактирования#

Обзор#

# hack hack
git status # Optional
git diff # Optional
git add modified_file
git commit
# push the branch to your own Github repo
git push origin my-new-feature

Более подробно#

  1. Внесите некоторые изменения. Когда вы почувствуете, что сделали полный, рабочий набор связанных изменений, переходите к следующим шагам.

  2. Опционально: Проверьте, какие файлы изменились с помощью git status (см. git status). Вы увидите список, подобный этому:

    # On branch my-new-feature
# Changed but not updated:
#   (use "git add ..." to update what will be committed)
#   (use "git checkout -- ..." to discard changes in working directory)
#
#  modified:   README
#
# Untracked files:
#   (use "git add ..." to include in what will be committed)
#
#  INSTALL
no changes added to commit (use "git add" and/or "git commit -a")

  3. Опционально: Сравните изменения с предыдущей версией, используя git diff (git diff). Это открывает простой текстовый интерфейс браузера, который подсвечивает разницу между вашими файлами и предыдущей версией.

  4. Добавьте все соответствующие изменённые или новые файлы с помощью git add modified_file (см. git add). Это помещает файлы в промежуточную область, которая представляет собой очередь файлов, которые будут добавлены в ваш следующий коммит. Добавляйте только файлы, имеющие связанные, завершённые изменения. Оставляйте файлы с незавершёнными изменениями для последующих коммитов.

  5. Чтобы зафиксировать подготовленные файлы в локальной копии вашего репозитория, выполните git commit. На этом этапе откроется текстовый редактор, чтобы позволить вам написать сообщение коммита. Прочитайте раздел сообщения коммита чтобы убедиться, что вы пишете правильно отформатированное и достаточно подробное сообщение о коммите. После сохранения вашего сообщения и закрытия редактора ваш коммит будет сохранён. Для тривиальных коммитов короткое сообщение о коммите может быть передано через командную строку с использованием -m флагом. Например, git commit -am "ENH: Some message".

    В некоторых случаях вы увидите эту форму команды commit: git commit -a. Дополнительный -a флаг автоматически фиксирует все измененные файлы и удаляет все удаленные файлы. Это может сэкономить вам набор многочисленных git add команды; однако, это может добавить нежелательные изменения в коммит, если вы будете неосторожны. Для получения дополнительной информации см. зачем флаг -a? - и полезное описание варианта использования в проблема запутанной рабочей копии.

  6. Отправьте изменения в ваш форкнутый репозиторий на github:

    git push origin my-new-feature

    Для получения дополнительной информации см. git push.

Примечание

Предполагая, что вы следовали инструкциям на этих страницах, git создаст стандартную ссылку на ваш github репозиторий под названием origin. В git >= 1.7 вы можете гарантировать, что ссылка на origin будет постоянно установлена с помощью --set-upstream опция:

git push --set-upstream origin my-new-feature

Отныне git будет знать, что my-new-feature связано с my-new-feature ветку в вашем собственном github репозиторий. Последующие вызовы push затем упрощаются до следующего:

git push

Вам необходимо использовать --set-upstream для каждой новой создаваемой ветки.

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

Написание сообщения коммита#

Сообщения коммитов должны быть понятными и следовать нескольким базовым правилам.

Пример:

MAINT/TST: fft: remove xp backend skips, test `fftfreq` `device`

The first line of the commit message starts with a capitalized acronym
(or multiple, options listed below) indicating what type of commit this is.
Then a blank line, then more text if needed.
References to code names should be enclosed in backticks.
If changes are limited to certain submodules or functions, they should be
included after the acronym(s) - backticks are not needed here.

Пример:

BUG:sparse.linalg.gmres: add early exit when `x0` already solves problem

Lines shouldn't be longer than 72 characters. If the commit is related to an issue,
indicate that with "See gh-3456", "Closes gh-3456", or similar,
in the extended description.
However, if you are pushing many commits to a PR, you should avoid including
this in every commit message as it will clutter the linked issue.

Описание мотивации для изменения, характера ошибки для исправлений багов или некоторых деталей о том, что делает улучшение, также хорошо включать в сообщение коммита. Сообщения должны быть понятны без просмотра изменений кода. Сообщение коммита, такое как MAINT: fixed another one является примером того, чего не следует делать; читателю приходится искать контекст в другом месте.

Стандартные акронимы для начала сообщения коммита:

API: an (incompatible) API change
BENCH: changes to the benchmark suite
BLD: change related to building SciPy
BUG: bug fix
DEP: deprecate something, or remove a deprecated object
DEV: development tool or utility
DOC: documentation
ENH: enhancement
MAINT: maintenance commit (refactoring, typos, etc.)
REV: revert an earlier commit
STY: style fix (whitespace, PEP8)
TST: addition or modification of tests
REL: related to releasing SciPy

Примечание

Вы можете добавить некоторые маркеры, чтобы пропустить часть непрерывной интеграции. См. Непрерывная интеграция.

Запрос на слияние ваших изменений с основным репозиторием#

Когда вы считаете свою работу завершенной, вы можете создать запрос на слияние (PR). На GitHub есть полезная справочная страница, описывающая процесс для создание pull request'ов.

Если ваши изменения включают модификации API или добавление/изменение функции, вы должны инициировать ревью кода. Это включает отправку письма на Форум SciPy со ссылкой на ваш PR вместе с описанием и обоснованием ваших изменений.

Контрольный список перед отправкой PR#