Блог
Публикации о процессе разработки, решённых задачах и изученных технологиях
Как README потерял справочник и вернул его обратно
Три месяца назад в проекте Speech to Text произошла история, которая напомнила мне, почему техническая документация — это не маркетинг. Всё началось просто: кто-то решил переписать README, сделав его более дружелюбным и компактным. На первый взгляд, идея имела смысл. Один-пейджер вместо стены текста — казалось, это сделает проект более привлекательным для новичков. Но забыли про опытных пользователей, которые полагаются на справочник. После публикации v2.0.9 в наш репозиторий начали поступать вопросы. Где конфиг? Как настроить модель вручную? Что делать, если Whisper начал галлюцинировать на русском тексте? Ответы были в коде, в issues, в старых документах — но не в README. Выяснилось, что при переписи выпало всё самое важное: раздел о конфигурации с примерами `config.json`, инструкции по сборке EXE и публикации релизов, таблицы зеркал для скачивания моделей из Hugging Face. Последнее особенно критично для тех, кто находится за корпоративными фильтрами или в странах с ограничениями: справочник содержал адреса альтернативных репозиториев, включая cascade's Whisper-AI и ONNX дарирующие файлы. Пришлось восстанавливать. Я прошёлся по старым версиям, собрал разделы про использование (пункты меню трея, вкладки Settings), про переопределение конфигурации через реестр моделей, про структуру проекта с новыми компонентами v2.0.9 — pyannote_onnx_lite, wespeaker_onnx, hallucination_filter, text_normalizer. Добавил troubleshooting с советом по Whisper hallucinations и tips по дарирации, упомянул debug_save_audio для отладки. Главное понимание, которое пришло в процессе: README — это не маркетинг. Это справочник, который пользователь открывает на шестой минуте ночи, когда в production что-то сломалось. Он не ищет вдохновляющего слогана, он ищет таблицу, точный пример конфига или команду для отладки. Вводная часть может быть красивой, но справочные разделы должны быть полными и точными. Итог: вернули всё, что было. Теперь README одновременно красивый и полезный — маркетинг в начале, справочник в конце, both на русском и английском. 😄 Совет дня: перед тем как обновить Rails, сделай бэкап. И резюме.
Когда regex ломает сборку: охота на призрака в version.py
Работаю над **Speech to Text** — проект с поддержкой CUDA-сборок для GPU-ускорения. Наша система так устроена: CI собирает CPU-версию, а локально я публикую CUDA-релизы через `publish_cuda.sh`. Скрипт берёт версию из `src/version.py`, упаковывает всё, подписывает ed25519-ключом и отправляет на зеркало. Казалось бы, рутина. Но вот беда: при публикации версии 2.0.9 сборка начала брать неправильный номер версии. `build.py` читает версию через regex, и вместо `2.0.9` собралась какая-то `X.Y.Z`. Первый подозреваемый — `src/version.py`. Открываю файл... aha! В файле была строка-пример в docstring-е: `"X.Y.Z"`. И regex в `build.py` её нашла! Это была классическая проблема: regex ищет `__version__ = "..."`, но не якорится к началу строки, так что подхватывает даже примеры в комментариях. Первый фикс: **переместить настоящий `__version__ = "2.0.9"` в самое начало файла** как первое присваивание. Второй фикс: в самом `build.py` добавить якорь `^` с флагом `re.MULTILINE` в regex. Теперь он ищет присваивание только в начале строки — пример в docstring больше не сбивает с толку. Но ладно, сборка прошла. Дальше — запуск на Windows. И тут выясняется, что в `voice_app.spec` в какой-то print-строке была стрелка Unicode `→`, и консоль Windows в кодировке cp1251 не может её вывести. Падает. Заменяю на `->` — готово. Такие мелочи в публикации релизов выглядят наивными, пока не сломают процесс. Regex без якорей, примеры в docstring-ах, которые мешают парсингу, Unicode в местах, где ожидают ASCII — всё это живёт где-то на грани видимости. Поэтому когда что-то вдруг не работает при локальной сборке, стоит смотреть не на сложные части, а на простые: как именно код *читает* данные, что находится рядом с этими данными, и включает ли парсер якори для границ. Кстати, про yakori — напомнило мне шутку про Kubernetes 😄 Почему Kubernetes лучший друг разработчика? Потому что без него ничего не работает. С ним тоже, но хотя бы есть кого винить.