Skip to content

Latest commit

 

History

History
224 lines (159 loc) · 16.3 KB

CONTRIBUTING.md

File metadata and controls

224 lines (159 loc) · 16.3 KB
Raw

Коллективное участие в проекте

Простой чек-лист использования

  • если скачали в первый раз, выполните opm run init
  • для сборки\компиляции только внешних файлов выполните opm run cepf - все соберется, только тестовые ИБ не будут обновлены
  • для выгрузки\декомпиляции своих изменений в исходники opm run depf
  • и стандартный процесс Гитхаба - Пулл-реквесты и т.д.

Ниже есть более подробные описания всех этих действий и возможных проблем.

  • Мы используем подход git-flow для реализации функциональности
  • Старайтесь создавать тесты в формате BDD или пишите модульные тесты.
  • Наличие тестов не всегда является обязательным. При каждой новой доработке используем индивидуальный подход для облегчения входа новых контрибьюторов и ускорения появления полезной функциональности
    • Мы используем принцип самопроверки через feature файлы, поэтому перед разработкой новой функциональности мы также - разрабатываем feature файлы, генерируем шаблоны сценариев и наполняем их кодом для проверки.
    • Также возможно обычные модульные тесты, написанные кодом 1С.

Прежде чем создавать задачи (issues) GitHub

  • старайтесь ознакомиться с документацией по проекту с помощью поиска
  • старайтесь ознакомиться с уже имеющимися задачами с помощью поиска, включая закрытые задачи
  • ознакомьтесь с каталогом features для понимания уже существующего и стабильного функционала
  • будьте в курсе изменений по проекту
    • нажмите watch и star, чтобы получать оповещения об изменениях

Старайтесь создавать задачи в формате BDD

  • Формат описания, если вы нашли "недочёт" (bug)
Дано <имею версию проекта>
  И <версию операционной системы>
  И <версию 1С предприятия>
  И <параметры совместимости конфигурации>
  • Формат описания, если хочется добавить новый функционал (enhancement)
Функционал: <Краткое описание>
Как <роль кому нужен функционал>
Чтобы <цель того кому нужен данный функционал>

Как добавить функционал к проекту

мы используем Example mapping, поэтому:

  • всё, что не имеет feature-файла - это просто вопрос или "вброс"
  • если существует feature-файл только с заголовком - это предварительное требование
  • если в feature-файле есть Сценарии - это требование с правилами реализации
  • есть в Сценарии есть шаги - это требование с правилами и примерами

Соответственно, помимо задач, можно использовать концепцию

  • git-flow - коллективная разработка с помощью github
  • pull-request - для черновиков функционала используется каталог .\features\Drafts

Процесс коллективной разработки

в соответствии с принципами Agile и Open Source мы используем

  • итеративный подход к разработке
  • первоначально мы решаем недочёты, а уже затем дорабатываем функционал
  • приоретизация и порядок доработки остаются на усмотрение команды контрибьюторов

однако это можно изменить 3-мя способами:

Pull-request

Первичная настройка

если вы разработчик

  • Установите oscript, git и проверьте, что данные находятся в переменной PATH,

    • т.е. git, oscript, opm вызываются без указания полного пути в коммандной строке.

  • Дополнительно должен быть установлен пакет vanessa-runner,

    • делать это надо в командной строке opm install vanessa-runner
      • возможно, от имени администратора.

  • сделайте fork репозитория

  • склонируйте репозитарий себе на машину git clone https://github.com/*ТУТИМЯВАШЕГОПОЛЬЗОВАТЕЛЯ*/add.git

  • переходим в склонированный каталог через cd add и выполняем несколько магических комманд

git remote add upstream https://github.com/vanessa-opensource/add.git
git fetch upstream
git checkout -b develop upstream/develop
git pull upstream develop

  • Далее нужно установить необходимые зависимости:

    • в консоли от имени администратора перейти в папку add и запустить opm install.
    • Результатом будет установленные пакеты, необходимые для работы скриптов.
    • Этот шаг необходимо сделать всего 1 раз.

  • Для начала разработки необходимо первичную настройку

    • инициализировать базовую базу данных для разработки

    • и из исходников собрать epf-файлы

    • Выполняем

    cd add
    opm run init

ВНИМАНИЕ: команды opm необходимо выполнять в обычном виндовом cmd\far , но не в bash-консоли, т.к. не сможет найти команду opm

Штатная разработка/доработка

Выбор задачи и предварительная подготовка

  • реализуйте функционал или возьмите в работу какую-то задачу

    • обратите внимание - некоторые задачи могут иметь награду DONATIONS.md

  • На основании ветки develop создаем новую ветку с номером задачи или кратким описанием

    • Например, feature/issue-9999
git checkout -b feature/issue-9999

Напоминаем, что все шаги git можно выполнять как из консоли git, так и из графического клиента для git (SourceTree, GitExtensions и т.п.)

  • теперь нужно собрать бинарные файлы из исходников. Для этого запустите сборку: opm run cepf

ВНИМАНИЕ: текущая версия opm использует версию библиотеки fs, которая не поддерживает некоторые методы, использующиеся в скриптах сборки. Поэтому необходимо

  • либо запускать задание вызовом oscript tasks/cepf.os,
  • либо обновить локальную установку fs внутри opm (запустить opm install -l fs в каталоге установки opm).
Изменения в плагинах/фичах/шагах/тестах
  • в каталоге add\features добавьте новый feature-файл, если необходимо
  • или в каталоге add\tests добавьте новый тест-файл, если необходимо
  • отредактируйте при необходимости add\bddRunner.epf или add\xddTestRunner.epf
    • или плагины в каталоге plugins
  • разработайте шаги проверки в add\features\* для вашего файла
  • или тесты в своем файле тестов
  • после всех доработок можете запустить в каталоге проекта opm run vanessa для проверки на управляемых формах, что ничего не сломали из стандартного функционала.
  • или прогоните тесты opm run xdd

Можно воспользоваться Чек-листом создания фичи для самотестирования Vanessa-ADD.

При готовности зафиксировать изменения необходимо теперь сделать обратную операцию в виде разборки *.epf на исходники:

  1. Массово выполните команду opm run depf * все обработки будут разобраны на исходники

ВНИМАНИЕ: возможно будет долгая операция, т.к. скрипт найдет все epf-файлы во всех подкаталогах и попробует их разобрать на исходники

  1. Для ускорения разборки * можно указать определенный каталог opm run depf ./features/libraries разберет только все обработки из ./features/libraries в этот же каталог по подкаталогам
* Выгрузить обработку вручную в конфигураторе отдельно:

  * в конфигураторе в окне внешней обработке в меню `Действия -> Выгрузить файлы` выбираем `Внешняя обработка в иерархическом формате` и указываем путь, где будет она находиться.
    > Например:
    + для `bddRunner.epf` и `xddTestRunner.epf` это путь в `epf/bddRunner` и `epf/xddTestRunner`,
    + для всех остальных каталогов это подкаталог с именем обработки в каталоге, где лежит обработка
      + Например, `plugins/ЗагрузчикФайла.epf` нужно положить в каталог `plugins/ЗагрузчикФайла`
  • В гите проверить необходимые изменения в исходниках и зафиксировать только их.

Внимание: платформа каждый раз меняет файлы Form.bin (для обычных форм), даже если разработчик их не менял. Соответственно, не надо добавлять Form.bin в гит, если вы не изменяли толстые формы.

Команды для программного добавления необходимых файлов в git

* Смотрим, какие файлы изменились - `git status`

      Изменения, которые не в индексе для коммита:
        (используйте «git add <файл>…», чтобы добавить файл в индекс)
        (используйте «git checkout -- <файл>…», чтобы отменить изменения
        в рабочем каталоге)

        изменено:      epf/bddRunner/bddRunner/Forms/УправляемаяФорма/Ext/Form/Module.bsl

      нет изменений добавленных для коммита
      (используйте «git add» и/или «git commit -a»)
Изменения в конфигурации

Если вы дорабатывали конфигурацию базы, например, добавляли метаданные для генерации тестовых данных, сохраните файл измененной конфигурации в соответствующие исходники конфигурации

  • lib/cf/83 - для bdd
  • lib/cf/83NoSync - с отключенными модальностью и синхронностью для bdd
  • lib/cf/83xdd - для tdd
Отправка изменений

  • Добавляем необходимые файлы в индекс

    • git add epf/bddRunner/bddRunner/Forms/УправляемаяФорма/Ext/Form/Module.bsl

  • Фиксируем изменения с комментарием git commit -m "Наш комментарий!"

  • Отправляем все изменения своей ветки на github git push origin feature/issue-9999

  • Далее формируем pull-request в интерфейсе github

Участие в архитектурных обсуждениях

если вы методолог или архитектор

  • сделайте свой первый pull-request, в том числе в документацию
  • создайте обсуждение https://github.com/vanessa-opensource/add/issues с описанием противоречия
  • участвуйте, обосновывайте, приводите примеры
  • используйте ТРИЗ для построения непротиворечивых решений

BSD v3 License

Наша лицензия поощряет коллективное участие в разработке всего стэка продуктов Vanessa Stack.

Поэтому:

  • используйте, дорабатывайте через концепцию fork и pull-request официальный продукт vanessa-opensource/add
  • если вы хотите создать свой продукт на основе vanessa-add, это разрешено и не противоречит лицензии BSD v3
  • однако, если вы хотите использовать для рекламирования и продвижения своего продукта бренды "Vanessa ADD" или "Vanessa ADD", вам необходимо получить у нас разрешение на это, создав Issue на GitHub

CLA - лицензия на коллективное участие

Мы придерживаемся https://cla.github.com/agreement что означает - Ваш вклад не нарушает никаких наших прав и не накладывает на нас никаких ограничений и обязательств.

Если ничего не понятно

  • запишитесь на практические занятия по правильной разработке 1С у Артур Аюханова aka artbear.