Документация исходного кода; установленный выпуск может отличаться.

Как участвовать в Projects Plus

English

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.

Форматирование настроено в репозитории. 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: английский, русский, украинский и упрощённый китайский. Ключи добавляйте или правьте во всех четырёх файлах. Подписи держите короткими, а незнакомые понятия объясняйте в руководстве пользователя.

Опорный текст — английский. Русские, украинские и китайские строки для недавних функций (раскладки и размер карточек галереи, поля карточки, изменяемые рамки карточек, миниатюры в канбане, вкладка «Фильтры» в настройках) написаны сопровождающими без проверки носителями языка. Правки от тех, кто пользуется плагином на этих языках, приветствуются:

Документация парная

У каждого документа есть версия на двух языках: файл с базовым именем и файл с суффиксом языка (-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.

  1. В ветке задайте версию командой npm version X.Y.Z --tag-version-prefix="" --no-git-tag-version. Хук version копирует её в manifest.json и добавляет в versions.json; сам он версию не повышает.

  2. Обновите обе истории изменений и двуязычный обзор выпуска, пересоберите документацию командой 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 без перезаписи рабочей копии.

  3. Слейте pull request и запушьте тег X.Y.Z — саму версию, без v — на коммите слияния. Релизный workflow отклоняет тег, не совпадающий с manifest.json, собирает плагин и публикует main.js, manifest.json и styles.css.

  4. Дождитесь успешного 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.

Исходник страницы ↗