Runbook выполнения и сдачи ПР

1. Подготовьте репозиторий

1. Создайте личный репозиторий на GitHub или GitVerse для ПР01–ПР06. Для ПР07–ПР14 используйте репозиторий команды, если работа уже ведётся вместе.
2. Добавьте workflow по инструкции курса.
3. Создайте перечисленные в условии пакеты, ноды, launch/config-файлы и тесты. Миры, bag/data fixtures, модели и public checker используйте как входные данные.
4. Скачайте комплект входных материалов, проверьте его SHA-256 и распакуйте в .course-kit/.

2. Запишите, где запускаете работу

1. Для ПР01–ПР04 выбрать одну из поддерживаемых сред.
2. Начните из нового терминала и запишите способ запуска, версии ОС, ROS 2, Gazebo, значение .course-kit/v1/VERSION и SHA-256 архива.
3. Для проектной среды и Gazebo-fixtures откройте .course-kit/v1/config/baseline.lock.yaml текущего выпуска и проверьте хэш.
4. В Docker сохраните digest образа и подключите рабочее пространство и evidence/ как каталоги хоста.

3. Сначала покажите сбой, затем исправляйте

• сохранить минимальный сценарий до исправления;
• внести требуемое собственное изменение;
• назвать основную причину и повторить тот же тест после исправления;
• сохранить только нужные логи и фрагменты bag-файла, без секретов и персональных данных.

4. Запустите проверки

В ПР01 выполните CLI-опыт и проверку JSON. В ПР02 добавляются сборка пакета turtle_bringup и проверка его launch по условию. Полный цикл с функциональными тестами своей ноды ниже нужен начиная с ПР03.

colcon build --symlink-install
colcon test
colcon test-result --verbose

Конкретные package/fixture команды указаны на странице ПР. Общий checker запускаем на шаге 7, после заполнения отчёта и декларации.

5. Два коммита: реализация и отчёт

SHA коммита, содержащего сам отчёт, в report.json записывать не нужно. При изменении отчёта изменился бы и SHA, поэтому используем два состояния:

A: реализация ──→ B: отчёт и AI_USAGE.md
                  report.commit = SHA(A)
                  сдаём SHA(B) + успешный CI для B

A содержит готовые код, конфигурацию, README и workflow. Для ПР01 достаточно README с командами и CI; начиная с ПР02 здесь также исходный ROS-пакет. B добавляет результаты проверок в evidence/prNN/ и обязательную декларацию AI_USAGE.md. Между A и B реализация не меняется.

Пример для ПР02

Выполняйте из корня своего репозитория. Для другой ПР замените PR02 и pr02. Перед коммитом A завершите изменения кода и CI, выполните проверки поведения. Логи можно уже сохранить в evidence/pr02/, но пока не включайте их в коммит.

git status --short
git add -- . ':!evidence' ':!AI_USAGE.md'
git diff --cached --name-only

Две записи с :! исключают результаты и декларацию из этого добавления. Если они уже были добавлены в индекс раньше, уберите их из staged через git restore --staged -- evidence AI_USAGE.md (только существующие в индексе пути); файлы на диске сохранятся. Убедитесь, что staged содержит только реализацию текущей работы, затем:

git commit -m "PR02: implement launch package and CI"
git rev-parse HEAD

Последняя команда печатает SHA(A) — 40 символов. Он уже существует и не изменится от создания следующего коммита. Если реализация уже закоммичена и не менялась, используйте её текущий SHA, пустой коммит не нужен.

6. Заполните отчёт и декларацию

Создайте отчёт из шаблона, если его ещё нет:

mkdir -p evidence/pr02
[ -e evidence/pr02/report.json ] || cp .course-kit/v1/practices/templates/report.json evidence/pr02/report.json
[ -e AI_USAGE.md ] || cp .course-kit/v1/practices/templates/AI_USAGE.md AI_USAGE.md

В report.json заполните номер ПР, версию и SHA-256 course kit, реальные команды и проверки, воспроизведение сбоя, причину, результат исправления, затраченное время и ai_used. Не оставляйте значения replace-with-*. В AI_USAGE.md добавьте раздел PR02 с помощью ИИ и способом её проверки либо записью «ИИ не использовался». Согласуйте её с ai_used в отчёте.

SHA(A) можно вставить в поле commit вручную или записать без копирования следующей командой до создания коммита B:

python3 - <<'PYCODE'
import json
import subprocess
from pathlib import Path

path = Path('evidence/pr02/report.json')
report = json.loads(path.read_text(encoding='utf-8'))
report['commit'] = subprocess.check_output(
    ['git', 'rev-parse', 'HEAD'], text=True,
).strip()
path.write_text(json.dumps(report, ensure_ascii=False, indent=2) + '\n', encoding='utf-8')
print('report.commit =', report['commit'])
PYCODE

7. Зафиксируйте отчёт и отправьте сдачу

python3 .course-kit/v1/tools/check_practice.py PR02 --submission .
git add evidence/pr02 AI_USAGE.md
git diff --cached --name-only
git commit -m "PR02: record evidence and AI usage"
git rev-parse HEAD

Убедитесь до второго git commit, что staged содержит только evidence/pr02/ и AI_USAGE.md. Теперь последняя команда печатает SHA(B). Значение report.commit остаётся SHA(A) — не заменяйте его на новый HEAD. Выполните git push в настроенную ветку GitHub/GitVerse. Дождитесь зелёного CI для B и сдайте ссылку на репозиторий, SHA(B) и ссылку на этот CI run.

Если понадобилась доработка

• Меняли только отчёт, логи или декларацию: добавьте новый evidence-коммит, оставьте SHA(A) в отчёте и сдайте новый SHA с его CI.
• Меняли код, README, зависимости или CI: создайте новый коммит реализации A2, повторите затронутые проверки, запишите SHA(A2) в отчёт и создайте B2.
• Не используйте git commit --amend для попыток «подогнать» SHA отчёта под содержащий его коммит. Checker проверяет, что указанная реализация существует в истории и с тех пор менялись только evidence текущей ПР и декларация.

8. Доработайте на лабораторной

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