Вклад

Большое спасибо за ваш вклад в Davinci! Прежде чем вносить свой вклад, пожалуйста, внимательно прочитайте следующие инструкции.

Категории вклада

Обратная связь и исправление ошибок (Bug)

Мы рекомендуем при обратной связи или исправлении ошибок сначала создать Issue для подробного описания ситуации с ошибкой, чтобы сообщество могло найти и просмотреть проблему и код. Обратная связь по ошибкам обычно должна включать полное описание информации об ошибке и воспроизводимый сценарий, чтобы сообщество могло быстро определить причину ошибки и исправить её. Открытые Issue с тегом #bug должны быть исправлены.

Общение, реализация и рефакторинг функций

В процессе общения подробно опишите детали, механизмы и сценарии использования новой функции (или рефакторинга), чтобы ускорить её реализацию. Если вы планируете реализовать важную функцию (или провести рефакторинг), обязательно обсудите это с основной командой разработчиков через Issue или другим способом, чтобы мы могли эффективно продвигать её вперёд. Открытые Issue с тегами #feature — это новые функции, которые необходимо реализовать, а открытые Issue с тегами #enhancement — функции, требующие улучшения или рефакторинга.

Ответы на вопросы по Issue

Помощь в ответах на вопросы пользователей в Issue — это ценный способ внести свой вклад в сообщество Davinci; в сообществе всегда будут появляться новые пользователи, и, помогая им, вы также можете продемонстрировать свои профессиональные знания.

Улучшение документации

Документация пользователя Davinci находится в каталоге docs/, мы используем jekyll в качестве службы документации Davinci, вы можете редактировать файлы Markdown в этом каталоге для улучшения документации.

Интернационализация

К сожалению, Davinci в настоящее время поддерживает только китайский язык; но интерфейс проекта зависит от [react-intl], и структура кода также поддерживает интернационализацию. Мы приветствуем вклад в другие языки.

Процесс вклада

Структура ветвей

В исходном коде Davinci могут быть созданы временные ветви, но только три из них имеют чёткое значение:

• dev-0.3: основная ветвь разработки, обратите внимание, что код в ветке dev-0.3 не гарантирует работоспособности, используйте его осторожно;
• master: исходный код последнего стабильного выпуска, иногда с несколькими исправлениями;
• dev-0.2: исходный код версии 0.2, версия 0.2 больше не обновляется, если у вас есть пользователи версии 0.2 или вам нужно продолжить разработку, вы можете обратиться к этой ветви.

Инструкции по разработке

Код переднего и заднего плана Davinci использует один и тот же кодовый репозиторий, но они разделены в разработке. Прежде чем начать разработку, пожалуйста, сначала разветвите проект Davinci на свой собственный Github Repositories, и разработайте на основе своего собственного кодового репозитория Davinci.

Если вы планируете внести свой вклад в код Davinci, мы рекомендуем клонировать ветку dev-0.3 для разработки, так как вероятность конфликтов при объединении PR будет намного меньше.

git clone https://github.com/yourname/davinci.git

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

git clone https://github.com/yourname/davinci.git --branch master

Фронтенд

Исходный код фронтенда находится в каталоге webapp/, скомпилированный файл фронтенда — в каталоге davinci-ui/.

Структура каталога

├── app              # Основной код приложения
  ├── assets           # Файлы ресурсов
  ├── components       # Общие компоненты
  ├── containers       # Компоненты маршрутизации
  ├── utils            # Общие методы
  └── app.tsx          # Главный вход приложения
├── internals        # Файлы разработки
├── libs             # Изменённые зависимости проекта
├── server           # Сервер разработки
├── share            # Исходный код страницы общего доступа
└── package.json

Разработка

npm install
npm start

Lint

npm run lint

Test

npm run test

Сборка

npm run build

Бэкенд

Конфигурация пользователя находится в корневом каталоге проекта /config/, проектный скрипт запуска и скрипт обновления находятся в корневом каталоге /bin/, код бэкенда и основная конфигурация находятся в каталоге server/, журналы находятся в корневом каталоге /log/. Обратите внимание: здесь все корневые каталоги относятся к каталогу, настроенному переменной среды DAVINCI3_HOME, при использовании IDE для разработки также необходимо настроить переменную среды, например, в Idea приоритет загрузки переменных среды: Run/Debug Configurations → Environment variables → IDE кэшированные системные переменные среды.

Структура каталогов

Скрипты

├── bin                   # Каталог скриптов
  ├── migration             # Скрипт миграции больших версий
  ├── patch                 # Скрипт обновления базы данных
     ├── 001_beta5.sql        # Опубликованный патч (имена: «последовательность_версия»)
     └── beta.sql             # Не опубликованный патч (фиксированное имя)
  ├── build.sh
  ├── davinci.sql           # Полный скрипт базы данных системы (включая все патчи)
  ├── initdb.bat            # Скрипт инициализации базы данных для Windows
  ├── initdb.sh             # Скрипт инициализации базы данных Shell для Linux, Mac
  ├── restart-server.sh     # Скрипт перезапуска сервера для Linux, Mac
  ├── run.bat               # Скрипт запуска ядра для Windows
  ├── start.bat             # Скрипт запуска сервиса для Windows
  ├── start-server.sh       # Скрипт запуска сервера для Linux, Mac
  ├── stop.bat              # Скрипт остановки сервиса для Windows
  └── stop-server.sh        # Скрипт остановки сервера для Linux, Mac

Конфигурации пользователя

├── config                          # Каталог конфигурации пользователя
  ├── application.yml.example         # Шаблон конфигурации приложения
  ├── datasource_driver.yml.example   # Шаблон пользовательской конфигурации
  └── logback.xml                     # Конфигурация журнала

Структура каталогов кода

├── server                                  # Корневой каталог кода сервера
   ├── src                                    # Исходный каталог
      ├── main
         ├── java
            └── edp
               ├── core                             # Основная конфигурация и общий код
               ├── davinci                          # Код бизнес-логики Davinci
               ├── DavinciServerApplication         # Класс запуска системы
               └── SwaggerConfiguration             # Класс конфигурации Swagger
         └── resources
            ├── generator
            ├── mybatis                           # Каталог отображения mybatis
            ├── templates                         # Каталог шаблонов электронной почты и Sql
            ├── application.yml                   # Файл конфигурации ядра системы
            └── banner.txt
      └── test                                # Каталог тестового кода
   └── pom.xml                              # Maven-конфигурация Davinci Server, наследуется от pom.xml корневого каталога проекта

Каталог журналов

├── logs        # Корневой каталог журналов
  ├── **Системный журнал**

sys  # системный журнал
└── user  # пользовательский журнал
    ├── opt  # журнал операций пользователя
    └── sql  # журнал SQL-запросов пользователя

Переменные среды

Рекомендуется настроить системную переменную среды DAVINCI3_HOME или переменную среды IDE.

База данных

1. Создайте базу данных системы Davinci самостоятельно.
2. Измените соответствующую информацию в bin/initdb.sh или bin/initdb.bat и выполните её или импортируйте файл bin/davinci.sql непосредственно в клиент базы данных.

Конфигурационный файл

Переименуйте файл application.yml.example в каталоге config/ в application.yml и настройте соответствующие атрибуты.

Упаковка

1. Чтобы создать полный пакет выпуска, необходимо изменить соответствующую информацию о версии в файле /assembly/src/main/assembly/assembly.xml в корневом каталоге, а затем выполнить команду mvn clean package в корневом каталоге.

2. Для создания пакета сервера можно выполнить команду mvn clean package непосредственно в каталоге server/.

Руководство по запросу на вытягивание (Pull Request)

• Если вы не знаете, как отправить PR в открытый проект, обратитесь к этому руководству.
• Независимо от того, исправляете ли вы ошибку или разрабатываете новую функцию, отправьте PR в ветку dev-0.3.
• PR и коммиты должны следовать принципу <type>(<scope>): <subject>. Подробнее см. в статье «Руководство по написанию сообщений о фиксации и журнала изменений» от Руань Ифэна.
• Если PR содержит новую функцию, обновление документации должно быть включено в этот PR.
• Если текущий PR ещё не готов к слиянию, добавьте префикс [WIP] (WIP = work-in-progress) в начало названия.
• Все коммиты, отправленные в ветку dev-0.3, должны пройти хотя бы один раунд проверки перед слиянием.

Стандарты проверки

Прежде чем вносить свой вклад в код, полезно узнать, какие типы коммитов приветствуются при проверке. Проще говоря, если коммит приносит как можно больше пользы и как можно меньше побочных эффектов или рисков, вероятность его слияния выше, и проверка будет выполнена быстрее. Коммиты с высоким риском и низкой ценностью практически никогда не объединяются, и их даже могут отклонить без рассмотрения.

• Польза:
  • исправление основных причин ошибок;
  • добавление или исправление функции или проблемы, которые срочно нужны большому количеству пользователей;
  • простота и эффективность;
  • лёгкость тестирования, наличие тестовых случаев;
  • снижение сложности и объёма кода;
  • проблемы, которые обсуждались в сообществе и были признаны требующими улучшения.
• Побочные эффекты и риски:
  • только поверхностное исправление ошибок;
  • введение сложной новой функции;
  • добавление сложности для удовлетворения редких потребностей;
  • изменение стабильного существующего API или семантики;
  • нарушение нормальной работы других функций;
  • добавление большого количества зависимостей;
  • произвольное изменение версий зависимостей;
  • отправка большого объёма кода или изменений за один раз.
• Примечания проверяющего:
  • используйте конструктивный тон для написания комментариев;
  • если требуется, чтобы автор PR что-то изменил, чётко укажите все изменения, необходимые для завершения этого запроса на вытягивание;
  • если после слияния PR обнаруживаются новые проблемы, проверяющий должен связаться с автором PR и обсудить решение проблемы; если связаться с автором PR невозможно, проверяющий должен откатить этот PR.

Продвинутое руководство по вкладу

О коммиттерах (Collaborators)

Как стать коммиттером

Если вы внесли значительный вклад в PR проекта Davinci, который был объединён, вы можете оставить комментарий в этом Issue или связаться с основной командой разработчиков через официальный WeChat-группу, чтобы подать заявку на участие в проекте Davinci в качестве коммиттера. Основная команда разработчиков и другие коммиттеры проведут голосование, чтобы решить, разрешить ли вам присоединиться. Если вы получите достаточное количество голосов, вы станете коммиттером проекта Davinci.

Права коммиттеров

• Возможность присоединиться к официальной группе разработчиков WeChat и участвовать в обсуждениях и разработке планов развития.
• Возможность управлять Issue, включая закрытие и добавление тегов.
• Возможность создавать и управлять ветвями проектов, кроме master, dev-0.3 и dev-0.2.
• Возможность проверять PR, отправленные в ветвь dev-0.3.
• Возможность подавать заявки на членство в комитете.

Комитет

Как стать членом комитета

Если вы являетесь коммиттером проекта Davinci и ваш вклад получил одобрение других членов комитета, вы можете подать заявку на вступление в комитет Davinci. Другие члены комитета проведут голосование, чтобы определить, разрешить ли ваше присоединение. Если все проголосуют «за», вы станете членом комитета Davinci.

Права членов комитета

• Возможность объединять PR, отправленные другими коммиттерами и участниками в ветвь dev-0.3.