Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
187 lines (141 loc) · 13 KB

CONTRIBUTING.md

File metadata and controls

187 lines (141 loc) · 13 KB

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

Действующие соглашения:

  • внутренний идентификатор языка для разработчиков - bsl
  • имя пакета, устанавливаемого через пакетный менеджер - language-1c-bsl
  • пользовательское имя языка, отображаемое при выборе синтаксиса - 1C (BSL)

Разработка грамматик

Для проверки корректности синтаксиса используется node.js-пакет atom-grammar-test.
Разработку грамматик рекомендуется вести в редакторе Atom, сразу же проверяя ее корректность через заложенные в пакет atom-language-1c-bsl spec-тесты.
При отправке Pull request на GitHub рекомендуется приложить текст синтаксического теста в описании изменений.

Редактирование грамматики в Sublime Text

  • Настройте окружение как описано в разделе "Настройка окружения"
  • Убедитесь, что подсветка 1C (BSL) доступна и работает
  • Откройте файл 1c-syntax\1c.YAML-tmLanguage и внесите свои изменения
  • Запустите скрипты build.os и publish.os -st через интерпретатор или редактор
  • Изменения синтаксиса должны примениться автоматически. Если этого не произошло, попробуйте переоткрыть редактор
  • Сделайте коммит и отправьте изменения файла 1c.YAML-tmLanguage в основной репозиторий 1c-syntax

Редактирование в Atom

  • Настройте окружение как описано в разделе "Настройка окружения"
  • Откройте папку 1c-syntax в Atom в режиме разработчика
  • Добавьте в рабочую область папку atom-language-1c-bsl
  • Убедитесь, что подсветка 1C (BSL) доступна и работает
  • Откройте файл 1c.YAML-tmLanguage и внесите свои изменения
  • Запустите скрипты build.os и publish.os -atom через интерпретатор или редактор
  • Нажмите Ctrl-Alt-R
  • Откройте любой файл каталога atom-language-1c-bsl и запустите тесты командной Run package specs - тесты не должны падать
  • Сделайте коммит и отправьте изменения файла 1c.YAML-tmLanguage в основной репозиторий 1c-syntax

Редактирование в VSC

  • Настройте окружение как описано в разделе "Настройка окружения"
  • Откройте папку 1c-syntax
  • Добавьте в рабочую область папку vsc-language-1c-bsl
  • Убедитесь, что подсветка 1C (BSL) доступна и работает
  • Откройте файл 1c-syntax\1c.YAML-tmLanguage и внесите свои изменения
  • Запустите скрипты build.os и publish.os -vsc через интерпретатор или редактор
  • Перезапустите отладочный сеанс VS Code
  • Сделайте коммит и отправьте изменения файла 1c.YAML-tmLanguage в основной репозиторий 1c-syntax

Разработка пакетов

Общие положения

Функциональность пакетов для каждого из редакторов должна развиваться равномерно. Если для релиза v1.1.0 запланировано, например, добавление команд по запуску скриптов .os в onescript, то данная функциональность должна появиться во всех редакторах одновременно (за исключением случаев, когда принято решение о невключении данного функциональности в пакет какого-либо редактора).

По возможности разработку общего для всех редакторов функциональность следует вести в головном репозитории 1c-syntax с последующим применением конвертеров и билд-скриптов.

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

В случае обнаружения специфичной для одного из редакторов ошибки допустимо выпустить bug-fix релиз для одного из пакетов. При выпуске следующего общего релиза номера версий приводятся к общему номеру.

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

Настройка окружения для разработки

Важно:
Каталоги 1c-syntax и каталог пакета для редактора должны располагаться в одном родительском каталоге

Sublime Text

Склонируйте репозитории 1c-syntax и sublime-language-1c-bsl к себе на компьютер.
Cоздайте символьную ссылку в каталог пакетов:

  • откройте командную строку с правами администратора
  • перейдите в каталог пакетов командой cd %AppData%\Sublime Text 3\Packages
  • создайте символьную ссылку командной
    mklink /D "Language 1C (BSL)" полный/путь/к/вашему/репозиторию/sublime-language-1c-bsl
    Название каталога Language 1C (BSL) обязательно для корректной работы.

Средства отладки на официальном сайте не обозначены :)
Попробуйте использовать внешние пакеты, например, Plugin Debugger.

Atom

Склонируйте репозитории 1c-syntax и atom-language-1c-bsl к себе на компьютер. Cоздайте символьную ссылку в каталог пакетов:

  • Откройте командную строку
  • Перейдите в папку репозитория atom-language-1c-bsl
  • Выполните команду apm link --dev для создания ссылки
  • Выполните команду apm install для установки зависимостей пакета
  • Откройте папку пакета в Atom в режиме разработчика или выполните команду atom --dev .

После создания ссылки на пакет может потребоваться активация dev-пакета. В окне редактора откройте настройки (File -> Settings), перейдите в раздел Packages, найдите раздел Development packages, в этом разделе найдите наш пакет language-1c-bsl. Если доступна кнопка Enable, нажмите ее.

При таком подходе удалять или деактивировать основной пакет language-1c-bsl не нужно. При запуске Atom в обычном режиме будет использоваться основной установленный пакет, в режиме разработчка будет использоваться пакет из папки dev\packages\language-1c-bsl.

Подробную информацию об отладке можно найти в документации.

После внесения изменений в исходный код модуля, отлаживаемое приложение можно перезапустить нажатием Ctrl-Alt-R.

VSC

  • Склонируйте репозитории 1c-syntax и vsc-language-1c-bsl к себе на компьютер.
  • Откройте папку репозитория в VSC.

Подробную информацию об отладке и возможных проблемах можно найти здесь и здесь.

Чтобы запустить VSC в режиме отладки, нажмите F5. При этом так же загрузится отлаживаемый модуль.
После внесения изменений в исходный код модуля, отлаживаемое приложение можно перезапустить нажатием Ctrl-R или нажать соответствующую кнопку в панели отладки.

Сборка пакетов

Для публикации пакетов на Marketplace VSC должна быть установлена утилита публикации vsce. Утилиту можно поставить командой

npm install -g vsce

Так же вам понадобится Personal Access Token. Настройка утилиты vsce описана здесь, разделы "Get a Personal Access Token" и "Login to a Publisher". Используемое имя "Publisher" - xDrivenDevelopment.

Для публикации пакетов на Atom.io/packages необходимо сначала авторизоваться комадной apm login

Репозитории-подпапки 1с-syntax, atom-language-1c-bsl, sublime-language-1c-bsl и vsc-language-1c-bsl должны располагаться в одном родительском каталоге. В квадратных скобках указано откуда надо выполнять команды.

Первым пунктом необходимо увеличить номер версии в файле package.json репозитория 1с-syntax, сделать коммит и отправить изменения в удаленный репозиторий.

<version> обозначает версию пакета, устанавливаемого в package.json основного репо. "v<version>" означает строку, например, "v1.0.0".

[1с-syntax] `bump version in package.json && make a changelog && commit && push`
[1с-syntax] oscript -encoding=utf-8 build.os
[1с-syntax] oscript -encoding=utf-8 publish.os -commit

Скопировать нужные пункты Changelog.md в каждый из редакторов и сделать коммит

[sublime-language-1c-bsl] git push
[sublime-language-1c-bsl] git tag "v<version>"
[sublime-language-1c-bsl] git push origin "v<version>"

[vsc-language-1c-bsl] `bump version in package.json && commit`
[vsc-language-1c-bsl] git push
[vsc-language-1c-bsl] git tag "v<version>"
[vsc-language-1c-bsl] git push origin "v<version>"
[vsc-language-1c-bsl] vsce publish

[atom-language-1c-bsl] apm publish <version>