Ветки & Начальные точки с использованием bencher run

Ветка — это git ссылка (например, имя ветки или тег). При использовании подкоманды CLI bencher run, выберите Ветку с помощью опции --branch или переменной окружения BENCHER_BRANCH. Текущий git хеш также может быть указан с помощью опции --hash. Если Ветка не указана, то используется имя текущей git ветки, если оно доступно. В противном случае, по умолчанию используется main как Ветка. Аналогично, если git хеш не указан, используется текущий git хеш, если он доступен.

При непрерывном бенчмаркинге, то есть при бенчмаркинге в CI, вы часто захотите создать или изменить базу branch на уже существующей Ветке. Это называется Точка старта Start Point. Точка старта — это другая Ветка на определенной версии (и git хеш, если доступен). При использовании подкоманды CLI bencher run, выберите Точку старта с помощью опции --start-point. Кроме того, используйте опцию --start-point-hash, чтобы указать конкретный git хеш для Точки старта. Объем данных, копируемых из Точки старта, контролируется с помощью опции --start-point-max-versions. Аналогично, пороги могут быть скопированы из Точки старта с помощью флага --start-point-clone-thresholds. Чтобы предотвратить расхождение, используйте флаг --start-point-reset, чтобы всегда сбрасывать Ветку до Точки старта.

--branch <BRANCH>

Чтобы выбрать ветку, установите параметр --branch или переменную окружения BENCHER_BRANCH в имя, слаг или UUID для ветки. Если указанное значение является именем или слагом и ветка еще не существует, она будет создана для вас. Однако, если указанное значение является UUID, то ветка должна уже существовать. Если оба параметра указаны, параметр --branch имеет приоритет над переменной окружения BENCHER_BRANCH.

Если ни один из них не указан, Bencher CLI пытается найти текущую ветку git. Он начинает с поиска репозитория git в текущей рабочей директории. Если это не удается, он продолжает в родительскую директорию и повторяет попытки вплоть до корневой директории. Если репозиторий git найден, используется текущее краткое имя ветки. Однако, если репозиторий git не найден, по умолчанию используется ветка main.

--hash <HASH>

40-символьный хеш SHA-1 коммита. Если два отчета имеют одинаковые ветку и хеш, они будут считаться относящимися к одному и тому же коммиту. Следовательно, у них будет один и тот же номер версии ветки.

Если не указано, Bencher CLI пытается найти текущий git hash. Начиная с поиска git-репозитория в текущем рабочем каталоге. Если поиск неудачен, он переходит к родительскому каталогу и повторяет попытки до корневого каталога. Если git-репозиторий найден, то используется git hash HEAD текущей ветки.

--start-point <BRANCH>

Используйте указанное имя ветки, сокращенное название или UUID в качестве начальной точки для опции branch. Для GitHub это обычно основная ветка для запроса на перенос, а для GitLab это обычно целевая ветка для запроса слияния. Основной случай использования --start-point - это Statistical Continuous Benchmarking.

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

Если новая branch создается с начальной точкой, то последние данные и, опционально, пороги из указанной начальной точки будут скопированы. См. опцию --start-point-max-versions и опцию --start-point-clone-thresholds для получения более подробной информации.

Например, если feature_branch еще не существует, но main существует и имеет исторические данные. Тогда использование --branch feature_branch --start-point main будет:

1. Создать новую ветку с именем feature_branch
2. Скопировать последние данные из main в feature_branch
3. bencher run будет продолжен с использованием feature_branch

🐰 Примечание: При использовании переменных окружения их следует заключать в двойные кавычки (например, --start-point "$MY_BRANCH_ENV_VAR"), если вы хотите, чтобы bencher run не вызвал ошибку, когда MY_BRANCH_ENV_VAR не определен.

--start-point-hash <HASH>

Используйте указанный полный хэш Git в качестве Начальной точки для опции branch. Эта опция требует установки опции --start-point.

• Если branch не существует, он будет создан из start-point с указанным хэшем.
• Если branch существует и start-point, и указанный хэш одинаковы, то эта опция игнорируется.
• Если branch существует и либо start-point, либо указанный хэш отличаются, будет создана новая Head ветка branch из start-point с указанным хэшем.
• Если branch не существует и start-point не существует с указанным хэшем, тогда branch будет создан из последней версии start-point. Если start-point не существует, тогда branch будет создан без каких-либо исторических данных.
• Если branch существует и start-point не существует с указанным хэшем, будет создана новая Head ветка branch из последней версии start-point. Если start-point не существует, то эта опция игнорируется.

Если новая branch создается с Начальной точкой, тогда все последние данные и, при необходимости, Пороги из start-point с указанным хэшем копируются. См. опцию --start-point-max-versions и опцию --start-point-clone-thresholds для более подробной информации.

Например, если feature_branch существует с его Начальной точкой в ветке main с хэшем 32aea434d751648726097ed3ac760b57107edd8b тогда использование --branch feature_branch --start-point main --start-point-hash 68b12758509ca5e2b1e3983525625e532eb5f562 выполнит:

1. Удалит старую Head ветку feature_branch
2. Создаст новую Head ветку feature_branch
3. Скопирует все последние данные из main с хэшем 68b12758509ca5e2b1e3983525625e532eb5f562 в новую Head ветку feature_branch
4. bencher run затем продолжит использование новой Head ветки feature_branch

--start-point-max-versions <COUNT>

Укажите максимальное количество исторических версий ветки, которые будут включены из Начальной Точки для опции branch. Любые версии, превышающие это число, будут исключены. Значение по умолчанию — 64 версии. Эта опция требует установки опции --start-point.

Например, если существует feature_branch с Начальной Точкой в ветке main, и в main содержится 300 версий, то использование --branch feature_branch --start-point main --start-point-max-versions 100 включит в feature_branch только последние 100 версий main.

--start-point-clone-thresholds

Клонирует все Пороги из Точки старта для опции branch. Этот флаг требует установки опции --start-point.

• Если Порог не существует, он будет создан из Порога start-point.
• Если Порог существует и он такой же, как Порог start-point, то этот Порог фактически игнорируется.
• Если Порог существует и его модель отличается от модели Порога start-point, то старая модель будет заменена моделью Порога start-point.
• Если Порог существует, а Порог start-point не существует, то модель Порога удаляется.

Например, если существует feature_branch с Точкой старта, являющейся Веткой main, и main имеет Порог для встроенной localhost Тестовой среды и показателя latency, то использование --branch feature_branch --start-point main --start-point-clone-thresholds создаст новый Порог для feature_branch с Тестовой средой localhost и показателем latency.

--start-point-reset

Сброс указанной ветки. Когда установлена опция --start-point, ветка будет сброшена до указанной начальной точки. Это полезно для предотвращения отклонений в данных Статистического непрерывного тестирования производительности. Основной случай использования для --start-point-reset без указания начальной точки — это Относительное непрерывное тестирование производительности.

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

Если новая ветка создается с начальной точкой, то все самые последние данные и, при необходимости, Пороги из начальной точки на указанном хэше копируются. См. опцию --start-point-max-versions и опцию --start-point-clone-thresholds для получения более подробной информации.

Сбросы одной и той же ветки с одним и тем же ключом идемпотентности используют одну Голову ветки, поэтому параллельные задания одного запуска CI не сбрасывают ветку друг за другом. При запуске в GitHub Actions ключ автоматически устанавливается на текущую попытку запуска workflow. Последующие шаги того же запуска workflow, которые сбрасывают ветку, также используют эту Голову, поэтому задайте другой ключ для шага, которому нужно снова сбросить ветку.

Например, если feature_branch существует без начальной точки, использование --branch feature_branch --start-point-reset приведет к следующим действиям:

1. Удалит старую Голову feature_branch
2. Создаст новую Голову feature_branch без каких-либо исторических данных
3. bencher run затем продолжит, используя новую Голову feature_branch

--start-point-idempotency-key <KEY>

Использует указанный ключ как ключ идемпотентности для флага --start-point-reset. Ключом может быть любой текст. Установите либо опцию --start-point-idempotency-key, либо переменную окружения BENCHER_START_POINT_IDEMPOTENCY_KEY. Если --start-point-reset не установлен или ключ пуст, эта опция игнорируется.

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

При запуске в GitHub Actions ключом по умолчанию является текущая попытка запуска workflow. Все задания одного запуска workflow используют одну Голову ветки, а повторный запуск workflow создает новую Голову. Последующие шаги того же запуска workflow, которые сбрасывают ветку, также используют эту Голову, поэтому задайте другой ключ для шага, которому нужно снова сбросить ветку. Для других CI-провайдеров установите в качестве ключа значение, одинаковое для всех заданий одного запуска пайплайна (например, --start-point-idempotency-key "$CI_PIPELINE_ID" в GitLab CI/CD).

Например, если workflow запускает матрицу из трех заданий, каждое из которых использует --branch feature_branch --start-point main --start-point-reset --start-point-idempotency-key run-abc123, то:

1. Первое задание, отправившее отчет, создаст новую Голову feature_branch из main с ключом идемпотентности run-abc123
2. Два других задания используют ту же Голову feature_branch, так как у нее есть ключ идемпотентности run-abc123
3. Результаты всех трех заданий отображаются вместе в feature_branch

🐰 Поздравляем! Вы узнали все о Ветках & Начальных точках! 🎉

Продолжайте изучение материал: Испытательные платформы & Specs ➡