Инструкция по вкладам Jpom

Описание каталога

.
├── .gitee            => конфигурация Gitee
├── docs              => скрипты однокликовой установки и файлы версий
├── modules           => директория Java backend (agent, server)
   ├── agent          => код плагинов
   ├── common         => общий модуль этого проекта (плагины используют этот модуль)
   ├── server         => код серверной части
   ├── sub-plugin      => модуль плагинов
├── script            => некоторые общие скрипты
├── web-vue           => директория frontend Vue
   ├── .editorconfig   => конфигурация формата кода для frontend (Vue)
├── .editorconfig      => глобальная конфигурация формата кода
├── .gitattributes     => конфигурация кодировки файлов
└── ....               => некоторые стандартные настройки репозитория

Некоторые правила1. После написания кода, при условии, что это не влияет на работу других участников, следует форматировать его согласно установленным правилам.

1. Используйте отступ в четыре пробела, запрещено использование символа табуляции.
2. При использовании табуляции для отступа, необходимо установить один таб как четыре пробела. В IDEA установите таб как четыре пробела, но не выбирайте "Использовать символ табуляции"; в Eclipse обязательно выбирайте "Заменять табуляцию пробелами".
3. Для новых методов в Java коде должны присутствовать полные и стандартизованные комментарии JavaDoc.
4. При исправлении ошибок или добавлении новых функций, пожалуйста, используйте минимальный способ коммита, чтобы минимизировать количество функций в одном коммите.
5. Все URL-адреса API должны следовать шаблону с нижним подчеркиванием.
6. Код и методы Java должны следовать правилу camelCase.
7. Имена классов Java должны следовать правилу PascalCase.
8. Для всех проектов на фронтенде рекомендовано использовать форматирование через Prettier (необходимо установить плагин).
9. Все контроллеры должны иметь документацию (должна содержать описание действия, параметров, возвращаемых значений и документацию apiDoc).> Примечание: Из-за множества нестандартных особенностей старого кода, он будет постепенно адаптироваться к новым стандартам. Для нового кода все указанные выше правила обязательны.

Правила документации классов (Javadoc)

/**
 * xxxxxxxx
 * @author xxxx
 * @since ${DATE}
 */

Здесь используется метка @since, так как в спецификации Javadoc нет метки @date.

Правила оформления кода Java

Рекомендуется установить плагин Alibaba Java Coding Guidelines (p3c)

Комментарии многострочных типов

https://www.e-learn.cn/topic/3680721## changelog Обновление правил

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

1. Если это баг, найденный пользователями, после его исправления следует указать никнейм обратившегося пользователя.
2. Если это задача Issue, следует указать адрес задачи и платформу (Gitee, GitHub).
3. Если это запрос Pull Request (PR), следует указать адрес запроса и платформу (Gitee, GitHub).
4. В зависимости от характера изменения определяется область влияния: если изменения затрагивают только агента (agent) или сервер (server), то используйте [agent], [server] в начале строки; если изменения затрагивают оба компонента, то начинайте запись без этих меток.
5. По необходимости можно добавить дополнительные примечания: такие как ссылка на коммит.
6. Примеры эмодзи: https://emojixd.com/## Документация API

[Обязательно] Все интерфейсы, которые должны быть включены в документацию apiDoc, должны иметь маркер @api.

Описание: Без маркера @api интерфейсы не будут отображаться в сгенерированной документации.

[Обязательно] Все маркеры документации apiDoc должны располагаться после маркеров документации JavaDoc.

Описание: Если маркер JavaDoc указан перед маркером apiDoc, то описание может быть включено в свойства маркера apiDoc, что не является желаемым поведением.

Пример верного использования:

/**
 * @author hjk
 * @api {method} path title
 * @apiParam {Number} id Уникальный идентификатор пользователя.
 */

Пример неверного использования:

Описание: Описание параметра id должно быть "Уникальный идентификатор пользователя". Если так будет указано, то описание станет "Уникальный идентификатор пользователя.@author hjk".

/**
 * @api {method} path title
 * @apiParam {Number} id Уникальный идентификатор пользователя.
 * @author hjk
 */

[Обязательно] Определение общих блоков документации

Описание: Используйте @apiDefine для определения общих блоков документации, затем используйте @apiUse для ссылки на эти блоки, чтобы повысить повторное использование блоков документации.

Все общие блоки документации должны быть определены в модуле server в пакете org.dromara.jpom.ApiDoc.1. Все новые функции должны быть добавлены в ветку dev, но не в ветку master. 2. Запросы Pull Request (PR) должны отправляться в ветку dev. 3. Для обычного развития функционала можно прямолинейно отправлять изменения в ветку dev. Для крупных функциональных изменений рекомендуется создание новой ветки для отправки изменений.

Необходимые группы

1. Группа backend (основная задача: разработка соответствующих интерфейсов в соответствии с требованиями).
2. Группа frontend (основная задача: оптимизация пользовательского интерфейса и взаимодействия, а также интеграция с некоторыми интерфейсами).
3. Группа документации (основная задача: улучшение и дополнение документации по использованию Jpom).
4. Группа видео (основная задача: создание видеоруководств по использованию Jpom).
5. Группа тестирования (основная задача: участие в внутреннем тестировании новых версий Jpom и выполнение ежедневных тестовых задач).