Инструкция по заполнению истории изменений¶

Типы записей¶

Каждая запись должна иметь один из трёх типов: New, Improved, Fix.

Общие правила¶

Одна запись — одно изменение¶

Не объединять несколько изменений в одну строку. Если исправлено три бага — это три записи.

Писать для пользователя, не для разработчика¶

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

❌ Убрана библиотека Hardcodet.Wpf.TaskbarNotification.dll

✅ Заменён механизм всплывающих подсказок

❌ Рефакторинг метода GetJoinedWalls

✅ Улучшена производительность соединения стен

Если изменение никак не влияет на пользователя (чисто внутренний рефакторинг, обновление зависимостей без видимого эффекта), его можно не включать в историю. Если включать всё же нужно, следует описать пользовательский эффект: "Уменьшено время загрузки плагина", а не "Обновлена версия библиотеки X".

Всегда конкретизировать¶

По умолчанию каждая запись должна быть конкретной. Запрещены произвольные расплывчатые формулировки:

❌ Мелкие исправления в коде

❌ Различные незначительные изменения

❌ Важные критические исправления в коде

❌ Исправлены некоторые ошибки

❌ Небольшие изменения в коде

Вместо этого — перечислить каждое исправление отдельной записью:

✅ Исправлена ошибка, при которой неверно определялся ближайший уровень в проектах с несколькими площадками

✅ Исправлена ошибка вылета при открытии проекта с отсутствующими общими параметрами

Допустимые исключения: стандартные заглушки¶

Бывают ситуации, когда плагин необходимо обновить, но описать изменения для пользователя невозможно — внутренний рефакторинг, обновление зависимостей, исправления, не воспроизводимые пользователем. В этих случаях допускается использовать ровно две стандартные формулировки:

[Improved] Сервисное обновление (внутренние изменения)

[Fix] Исправлены внутренние ошибки

Никакие другие варианты заглушек не допускаются. Если изменение можно описать конкретно — оно должно быть описано конкретно. Заглушки используются только как крайняя мера.

Грамматический стиль¶

Все записи формулируются в прошедшем времени, начиная с глагола женского или среднего рода в зависимости от подлежащего:

New: Добавлена / Добавлено / Добавлен
Improved: Улучшена / Оптимизирован / Обновлено / Упрощена / Изменён
Fix: Исправлена / Исправлен / Исправлено Не использовать:
отглагольные существительные ("Разворачивание содержимого окна...")
инфинитивы ("Добавить поддержку...")
номинативные конструкции без глагола ("Поддержка Revit 2027")

❌ Разворачивание содержимого окна плагина, если окно уже было открыто и содержимое было свернуто, при повторном запуске плагина

✅ Добавлено автоматическое разворачивание содержимого окна при повторном запуске плагина

Краткость¶

Запись должна быть одним предложением, по возможности — не длиннее двух строк. Убирать лишние слова, не несущие смысла.

❌ Исправлена ошибка, при которой в окно результатов не записывались ошибки, возникшие при неудачном изменении определения параметров

✅ Исправлена ошибка, при которой неудачные изменения определений параметров не отображались в окне результатов

Точки в конце записей не ставить¶

❌ Добавлена поддержка Revit 2027.

✅ Добавлена поддержка Revit 2027

Правила по типам записей¶

New¶

Используется для новой функциональности, которой раньше не было. Начинать с "Добавлен / Добавлена / Добавлено".

✅ Добавлена возможность в маске имени файла использовать параметры основной надписи

✅ Добавлен учёт дверей из витражных систем

✅ Добавлены счётчики прогресса обработки объектов

Не помечать как New изменения существующей функциональности:

❌ [New] Выполнен редизайн некоторых окон → это Improved

❌ [New] Убрано отображение ошибки "500 Internal Server Error" → это Improved или Fix

Improved¶

Используется для улучшений существующей функциональности. Указывать, что именно стало лучше.

❌ Улучшен экспорт

✅ Ускорен экспорт для проектов со связанными моделями

✅ Оптимизирована загрузка типоразмеров при работе с большими проектами

Типичные глаголы: Улучшена, Оптимизирован, Ускорена, Упрощён, Обновлён, Изменён, Расширен, Переработан.

Fix¶

Используется для исправления ошибок. Описывать симптом (что было сломано с точки зрения пользователя), а не причину (что было не так в коде).

❌ Исправлена ошибка null reference в WallUtils.GetJoinedWalls

✅ Исправлена ошибка вылета при соединении стен с разной структурой

❌ Исправлена ошибка локализации

✅ Исправлена ошибка, при которой некоторые элементы интерфейса отображались на английском языке

Если ошибка воспроизводилась только в определённых условиях, указать эти условия:

✅ Исправлена ошибка, при которой не работала сквозная нумерация при нумерации по кривой

✅ Исправлена ошибка, возникающая если в имени спецификации имеются недопустимые символы

Разграничение типов: пограничные случаи¶

Ситуация	Тип
Раньше плагин не запускался в документе семейства, теперь запускается	New — это расширение области применения
Ускорена работа существующей команды	Improved
Переработан интерфейс существующего окна	Improved
Добавлена проверка, предотвращающая вылет	Fix — пользователь видел вылет, теперь не видит
Добавлена новая команда в плагин	New
Добавлен новый параметр к существующей команде	New

Примеры хороших записей¶

[New] Добавлена возможность прервать обработку при объединении листов

[New] Добавлена поддержка Revit 2027

[New] Добавлена вкладка "Таблицы выбора" для поиска и удаления неиспользуемых таблиц

[Improved] Ускорен экспорт листов в проектах со связанными моделями

[Improved] Добавлено автоматическое разворачивание содержимого окна при повторном запуске плагина

[Improved] Оптимизирован поиск проёмов в витражах, являющихся ограждающими для помещений

[Fix] Исправлена ошибка, при которой после объединения листов мог замедляться AutoCAD

[Fix] Исправлена ошибка, при которой видовые экраны пропадали из листов после повторного открытия чертежа

[Fix] Исправлена ошибка "Метод не найден", возникающая в Revit 2027

[Improved] Сервисное обновление (внутренние изменения)

[Fix] Исправлены внутренние ошибки

Чек-лист перед добавлением записи¶

Указан тип (New / Improved / Fix)?
Запись начинается с глагола в прошедшем времени?
Запись описывает одно конкретное изменение?
Запись понятна пользователю без знания кода?
Нет расплывчатых формулировок? Если описать конкретно невозможно — использована одна из двух стандартных заглушек?
Запись не длиннее двух строк?
Нет точки в конце?
Тип записи соответствует содержанию?