Документация исходного кода; установленный выпуск может отличаться.
Как участвовать в Projects Plus
Projects Plus — плагин Obsidian, форк Obsidian Projects. Это руководство о том, как собрать плагин, изменить его и проверить результат. В рабочем пространстве сопровождающего разработка координируется через Borshkit. Начните с локального borshkit/START-HERE.md; контракты задач и доказательства приёмки — закрытые материалы пространства, не файлы исполнения плагина.
Собрать локально
Нужен Node.js 22 — та же версия, что в CI, — и npm. Из клона репозитория:
npm ci
npm run build
Сборка проверяет типы TypeScript и собирает плагин через esbuild. Файлы, которые нужны в хранилище: main.js, manifest.json и styles.css. Для пересборки на каждое сохранение запустите npm run dev.
npm run build и npm run dev перезаписывают сборочные файлы в копии проекта, включая отслеживаемый main.js. В рабочих копиях задач сопровождающего используйте изолированную сборку. Из корня рабочего пространства, с явными путями копии и результата:
node handoff/2026-10-07-claudex-to-borshkit/tools/build-branch.mjs <candidate-checkout> <output-directory>
Этот помощник находится в рабочем пространстве сопровождающего, а не в отдельном клоне репозитория. Он учитывает незакоммиченные изменения исходников и записывает хеши результата, не заменяя отслеживаемую сборку. Зависимости каждой рабочей копии задачи устанавливайте через npm ci; не подключайте общий node_modules через junction.
Чтобы проверить плагин в Obsidian, скопируйте эти три файла в .obsidian/plugins/obs-projects-plus/ отдельного тестового хранилища. Создайте папку, если её нет, включите плагин в настройках сторонних плагинов и перезагружайте его после каждой сборки. Работайте на примерных заметках: проверка редактирования и удаления меняет файлы хранилища.
Найти нужный код
Начните с карты устройства проекта. Плагин написан на TypeScript и Svelte, использует API Obsidian и хранилища Svelte. Точные зависимости и параметры компилятора — в package.json, package-lock.json и tsconfig.json.
Авторам сторонних видов нужен справочник API. Внутренние модули — детали реализации и могут меняться между выпусками.
Вносить изменение
Создайте ветку от main. Опишите задачу и поведение, которое должно получиться, и держите реализацию вместе с её документацией в одном pull request.
- Сохраняйте текст заметки при правке свойств. Используйте существующий data API и его путь через
processFrontMatterObsidian, а не перезапись файла целиком из компонента интерфейса. - Пишите настройки только существующим модулем записи настроек — иначе теряются повторные попытки, обнаружение конфликта и сообщение об отказе.
- Стройте DOM безопасными для текста способами. Для поддержки отдельных окон берите документ владеющего элемента или активный документ Obsidian.
- Проверяйте данные из настроек и пользовательский ввод. Где уместно, используйте помощники для регулярных выражений.
- Используйте переменные темы Obsidian и токены оформления. Управление должно работать с клавиатуры, а кнопкам без подписи нужны доступные имена.
- Освобождайте подписки, обработчики событий и прочие ресурсы при закрытии вида.
- Держите типы осмысленными. Неизбежные подавления объясняйте, а временный отладочный вывод убирайте до ревью.
Форматирование настроено в репозитории. npm run format переписывает весь src, поэтому просматривайте его диф и не приносите посторонних правок форматирования.
Проверить результат
Из корня репозитория:
npm run build
npm test -- --runInBand
npm run lint
npm run svelte-check -- --fail-on-warnings
Во время работы удобны точечные тесты; перед отправкой pull request прогоняйте весь набор. Тесты лежат рядом со своими модулями и в src/__tests__. Исправляя поведение, которое может вернуться, добавляйте покрытие. Для правки одной документации проверьте ссылки, примеры и тесты, которые сверяют изменённый справочный материал.
Изменения интерфейса нужно проверить и в Obsidian: откройте затронутый вид, выполните изменённое действие и убедитесь в результате после повторного открытия вида или перезагрузки плагина, если дело касается сохранения. Опишите в pull request хранилище, версию Obsidian и проделанные проверки — без содержимого личных заметок.
Матрица стабилизации 3.7.1 историческая. Для новых изменений приложите к pull request результаты автоматических проверок и ручных сценариев на затронутых устройствах с точным идентификатором сборки. Успех автоматики не заменяет приёмку на устройстве. Объём завершённого выпуска описан в обзоре 3.7.2.
Перевести интерфейс
Переводы интерфейса лежат в src/lib/stores/translations: английский, русский, украинский и упрощённый китайский. Ключи добавляйте или правьте во всех четырёх файлах. Подписи держите короткими, а незнакомые понятия объясняйте в руководстве пользователя.
Опорный текст — английский. Русские, украинские и китайские строки для недавних функций (раскладки и размер карточек галереи, поля карточки, изменяемые рамки карточек, миниатюры в канбане, вкладка «Фильтры» в настройках) написаны сопровождающими без проверки носителями языка. Правки от тех, кто пользуется плагином на этих языках, приветствуются:
- Сообщить о неудачной формулировке. Откройте issue по форме Translation: язык, где в плагине встречается текст, текущий вариант и ваше предложение. Снимок экрана помогает.
- Исправить самому. Найдите текущий текст в файле языка — так найдётся его ключ; поменяйте значение, ключ не трогайте. Каждую подстановку вида
{{count}}или{{name}}сохраняйте в точности, текст вокруг неё можно переставлять. - Проверить перед pull request.
npm test -- R0_26_i18nKeyCoverageпроверяет, что каждый ключ есть во всех четырёх файлах с теми же подстановками, аnpm test -- R0_30_sentenceCase— регистр в английском. - Если подпись не помещается в отведённое место, это тоже проблема вёрстки: напишите об этом в issue, а не сокращайте смысл.
Документация парная
У каждого документа есть версия на двух языках: файл с базовым именем и файл с суффиксом языка (-RU или -EN). Указатель docs/README.md, коды ошибок и две короткие страницы внутри хранилища держат оба языка в одном файле. Парность проверяет тест src/__tests__/R0_25_documentationPairs.test.ts: правите один язык — правьте и второй в том же коммите.
Отправить pull request
Напишите, что было не так, что происходит теперь и как вы это проверили. Для видимых изменений приложите снимки экрана, упомяните ограничения и проверки, которые выполнить не удалось. Обновляйте руководство пользователя или справочник API, когда меняется поведение. Изменения, заметные при обновлении, записывайте в CHANGELOG.md и CHANGELOG-RU.md.
Не включайте учётные данные, содержимое хранилища, локальные журналы и настройки, привязанные к вашей машине. Об ошибках сообщайте через GitHub Issues: шаги воспроизведения, версии плагина и Obsidian, операционная система, ожидаемый и фактический результат.
Выпустить версию
Релиз выпускается из main, который принимает изменения только через pull request с зелёной проверкой build.
В ветке задайте версию командой
npm version X.Y.Z --tag-version-prefix="" --no-git-tag-version. Хукversionкопирует её вmanifest.jsonи добавляет вversions.json; сам он версию не повышает.Обновите обе истории изменений и двуязычный обзор выпуска, пересоберите документацию командой
node scripts/build-docs-site.mjsи выполнитеnpm run docs:check. Соберитеnpm run buildв чистой копии с концами строк LF и закоммитьте полученныйmain.js: он хранится в Git и должен совпадать с релизной сборкой. Приcore.autocrlfв Windows пробелы Svelte могут унести\rв бандл; изолированная LF-копия позволяет повторить Linux CI без перезаписи рабочей копии.Слейте pull request и запушьте тег
X.Y.Z— саму версию, безv— на коммите слияния. Релизный workflow отклоняет тег, не совпадающий сmanifest.json, собирает плагин и публикуетmain.js,manifest.jsonиstyles.css.Дождитесь успешного CI, выпуска и публикации Pages. Сверьте опубликованные файлы и контрольные суммы, заметки к выпуску и ссылки сайта. Удаляйте слитые рабочие ветки после проверенного резервного копирования истории; сохраняйте постороннюю работу и рабочие деревья с незакоммиченными изменениями.
Бета для BRAT — это тег X.Y.Z-beta.N на коммите main, где X.Y.Z выше текущей версии (после 3.7.2 — 3.7.3-beta.1): workflow публикует её как предрелиз с бета-версией в манифесте релиза, не меняя manifest.json в main.
Лицензия и авторство
Вклад в плагин распространяется под Apache 2.0. Сохраняйте применимые уведомления об авторстве и лицензии. Оригинальный плагин создал Marcus Olsson, этот форк ведёт Park Pavel. Отдельный пакет типов объявляет лицензию MIT.