#1 перенос правил контрибутинга

2025-02-12 16:06:23 +02:00 · 2021-03-13 16:00:12 +03:00 · 2021-03-13 16:00:12 +03:00 · 2082615fea
commit 2082615fea
parent 9d0dc21a2f
2 changed files with 447 additions and 0 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -0,0 +1,239 @@
+# Участие в проекте 1С:Стандарты разработки V8
+
+Вначале, хотим поблагодарить Вас за желание участвовать в проекте!
+
+Далее описаны советы, как сделать свое участие наиболее эффективным для проекта и для себя. 
+Будьте благоразумны, если что-либо здесь не описано.
+
+## У меня есть вопрос
+
+1. Для начала убедитесь, что ответа нет в самой 1C:EDT.
+2. Информация в документации проекта
+
+**Вопрос есть, но ответа не нашел?** Создай `issue`  
+
+## Что я должен знать прежде чем начать
+
+Изучите текущую функциональность проекта, цели проекта, где находится граница возможностей плагина и 1C:EDT.
+
+Вопросы, которые не относятся к разаботке приложений в 1C:EDT по стандартам 1С, следует задавать в профильных сообществах.
+
+## Сообщить об ошибке
+
+Печально, что ошибка существует, но мы благодарны, что вы о ней нам сообщите!
+
+#### Прежде чем зарегистрировать
+
+* Проверьте [Wiki](https://github.com/1C-Company/v8-code-style/wiki) на наличие описания, что не является ошибкой
+* Проверьте раздел [Issues](https://github.com/1C-Company/v8-code-style/issues), чтобы не создавать дубликатов
+
+#### Как сообщить об ошибке эффективно
+
+Следуйте простым правилам:
+
+1. Задайте понятный заголовок `issue`, лаконично и исчерпывающе определяющий проблему
+    * постарайтесь не допускать двойного смысла, сленга из других областей и т.д. 
+    * Не используйте "метки" в заголовке - для этого существуют сами метки (labels)
+2. Опишите сценарий воспроизведения ошибки.
+    * скриншоты очень сильно помогают, но не заменяют сценарий
+    * добавьте логи ЖР, из лог-файлов (убедитесь, что они не содержат приватной информации)
+3. Опишите, что есть ошибка по вашему мнению и почему
+4. Опишите ожидаемое поведение
+
+
+## Предложите улучшение функциональности
+
+1. Задайте понятный заголовок `issue`, лаконично и исчерпывающе определяющий новую функциональность
+2. Опишите суть улучшений и обсудите в issue варианты реализации.
+3. Убедитесь совместно с авторами проекта, что ваше предложение не противоречит идеологии Стандартов 1С и 1C:EDT. При этом авторы проекта всегда рады обсуждению новых идей, всегда на стороне участников предлагающих улучшения, но при этом постараются максимально разъяснить случаи отказа в принятии идеи/реквеста, если возникнут.
+4. Реализуйте Ваше улучшение функциональности проекта в отдельном форке и предложите его через [Pull/merge request](#Pull-Requests-Merge-Requests)
+
+## Доработка кода
+
+### Написание проверок
+
+См. [Соглашение при создании проверок](Check_Convention.md)
+
+### Исправление ошибок
+
+* Создайте `issue` в проекте с описанием ошибки. Убедитесь, что владельцы проекта так же считают текущее поведение ошибочным.
+* Создайте ветку в своем **форке** с именем `bugfix/issue-<Номер issue>-доп-название`
+* Создайте **pull-request** из своей ветки в ветку **`master`** проекта v8-code-style
+* Убедитесь, что модификация кода действительно исправляет ошибку, описанную в issue, и не привносит новую функциональность - новую функциональность следует делать отдельным issue и pull-request'ом.
+* Следуйте общим правилам [Pull/merge request](#Pull-Requests-Merge-Requests)
+
+### Pull Requests (Merge Requests)
+
+* Создайте `issue` в проекте с описанием новой функциональности, желательно перед началом работы, чтобы исключить параллельную работу разных людей над одной задачей
+* Создайте ветку в своем **форке** с именем `feature/issue-<Номер issue>-доп-название`
+* Внесите изменения в конфигурацию или расширение
+* Создайте **pull-request** из своей ветки в ветку **`master`** проекта v8-code-style
+* Укажите ссылку на issue, которую закрывает данный pull-request
+* Установите в своем PR флажок "allow edits from maintainers"
+
+### Правила оформления коммитов
+
+Правила необходимы для предотвращения написания бессмысленных заголовков, мешающих пониманию ситуации на проекте. Хорошие оформленные коммиты помогают значительно облегчить процесс выяснения причин внесенных в код изменений, анализируя историю коммитов. Так же это необходимо для стилистического единообразия сообщений коммитов в репозитории.
+
+#### Тексты сообщений коммитов
+
+При написании сообщения коммита следует использовать формат:
+
+```
+#<НОМЕР ЗАДАЧИ> Короткое сообщение что сделано
+
+Длинное сообщение что сделано
+```
+
+1. Начинаем с номера задачи (например, #12311). Идентификатор необходим для интеграции с задачами GitHub
+2. В качестве разделителя между номером задачи и заголовком коммита используем пробел.
+3. Далее идет заголовок коммита:
+   - Пишем на русском языке.
+   - Заголовок с большой буквы.
+   - В конце заголовка точку не ставим.
+   - Желательно использовать настоящее время, а не прошедшее (например, "Исправление ошибок запуска при указанной web ИБ").
+   - Рекомендуем писать не слишком длинный заголовок, так как его отображение во многих интерфейсах выполнено в одну строку без переносов, так что, он может не влезть. Подробные детали пишем отдельным параграфом в описании коммита.
+4. Описание коммита (опционально).
+   - Отделяем от заголовка пустой строкой.
+   - Пишем полноценные предложения (начинаем с большой буквы, заканчиваем точкой)
+   - Хорошей практикой является ограничение длины строк в сообщении ≈72 символами, с добавлением переносов, если не влезает. Многие UI инструменты для GIT (в том числе EGit) не делают переносы текста описания, если он не влез.
+
+Контент сообщения коммита:
+
+В сообщении коммита пишем "что" и "почему" сделано, но избегаем деталей "как" сделано. Назначение комментария - дать коллегам понять, что происходит в проекте.
+
+1. Заголовок должен быть ёмкий и информативный.
+2. Заголовок должен быть написан официальным языком, без разговорных оборотов.
+3. Чтобы определить достаточность детализации заголовка коммита, попробуйте ответить на вопрос, не заглядывая в код:
+   - `[Bug]` Какая конкретно проблема здесь исправлена?
+   - `[Feature]` Какая функциональность здесь добавлена?
+   - `[Refactoring]` В каких компонентах/классах произведен рефакторинг?
+   - `[Tests]` Что они тестируют?
+   - `[Baseline]` В каком компоненте/плагине/пакете подняли версию/версии?
+   - `[Документация]` В каком компоненте добавлена документация?
+   - `[Исправление замечаний]` Какие именно проблемы вы исправили?
+4. Зачем писать сообщение коммита?
+   - Когда сделанные изменения неочевидны коллегам, то, помимо комментария в самом коде, не будет лишним описать детальнее, зачем эти изменения были сделаны или, почему сделаны именно так, а не иначе.
+   - При исправлении сложных багов можно воспользоваться методологией [Root_cause_analysis](https://en.wikipedia.org/wiki/Root_cause_analysis), и указать причину ошибочного поведения, а так же, каким образом это исправили. Человек (или даже вы сами), который через пару лет наткнется на неочевидное изменение, скажет вам спасибо.
+
+#### Количество коммитов
+
+Стоит ли делать один коммит на фичу - зависит от фичи. Коммит - логически завершенное изменение, а сложная фича может содержать много таких изменений, слияние которых в один коммит, приводит к потере информации о деталях ее выполнения. Это касается не только фич.
+
+Squash'ить коммиты стоит, если были сделаны лишнее изменения, которые в следующих коммитах отменили. Так же, стоит избегать коммитов вида "Поднятие версий", которые не являются самостоятельными (вызваны другими изменениями, без них билд проекта не будет выполнен).
+   
+### Лицензия
+
+Лицензирование расширений размещенных в данном проекте осуществляется на условиях свободной (открытой) лицензии Eclipse Public License - v 2.0 (полный текст лицензии - https://www.eclipse.org/legal/epl-2.0/)
+
+Это означает, что:
+- Вы можете  свободно и бесплатно заимствовать код  и помещать  его в свои проекты, учитывая  однако, что  такой  код не становится вашей интеллектуальной собственностью, Вы лишь  получаете  неисключительные права его использования с учетом рамок и ограничений,  описанных  в EPL 2.0 
+- Внося изменения в расширение, модифицируя и дорабатывая его, а также объединяя файлы расширения с иными материалами, не относящимися к расширению (далее по тексту как «результаты работ»), Вы также обязаны публиковать это  обновленный код на условиях EPL 2.0, т.е. автоматически предоставляете любым третьим лицам, включая ООО «1С-Софт» и иных контрибьюторов, безвозмездное право использования результатов Ваших работ на территории стран всего мира на условиях открытой лицензии EPL 2.0. 
+
+Загружая свои разработки, доработки и исправления к программам  других авторов Вы также подтверждаете, что:
+- являетесь единственным автором и обладателем имущественного права на результаты работ; в случае, если обладателем имущественного права на результаты работ является Ваш работодатель, Вы гарантируете наличие его согласия на публикацию кода на условиях открытой лицензии EPL 2.0;
+- Вы снабдили  результаты Ваших работ всеми необходимыми уведомлениями,  свидетельствующими о том, что они подчиняются открытой лицензии EPL 2.0;
+- Результаты Ваших работ доступны в виде исходного кода, или Вы обязуетесь сообщить, каким образом третьи лица без существенных затрат могут получить результаты Ваших работ в виде исходного кода; 
+- Bсе имеющиеся ранее уведомления других авторов (license notices) не были Вами удалены или изменены, а указанные Вами уведомления отражают достоверную информацию о Вас как правообладателе Вашего оригинального кода (включая ФИО или наименование организации-работодателя)
+
+
+Пояснения выше приведены исключительно для удобства восприятия основных положений лицензии EPL 2.0. и не заменяет содержание понятий, приведенных по тексту лицензионного соглашения. Для более детального понимания Ваших прав и обязанностей рекомендуем ознакомиться с полным текстом открытой лицензии EPL 2.0.
+
+Все файлы проекта, подлежащие лицензированию, должны иметь заголовок.
+
+```java
+/*******************************************************************************
+ * Copyright (C) 2021, 1C-Soft LLC and others.
+ *
+ * This program and the accompanying materials are made
+ * available under the terms of the Eclipse Public License 2.0
+ * which is available at https://www.eclipse.org/legal/epl-2.0/
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *
+ * Contributors:
+ *     1C-Soft LLC - initial API and implementation
+ *******************************************************************************/
+```
+
+##### Использование Eclipse Releng Tools для установки лицензии
+
+Установите дополнительный инструмент `Eclipse Releng Tools` из репозитория для соответствующей версии Eclipse JDK, например: [The Eclipse Project Updates - http://download.eclipse.org/eclipse/updates/4.16](http://download.eclipse.org/eclipse/updates/4.16)
+
+Добавьте в настройки согласно инструкции:
+
+https://wiki.eclipse.org/Development_Resources/How_to_Use_Eclipse_Copyright_Tool
+
+текст копирайта:
+
+```
+Copyright (C) ${date}, 1C-Soft LLC and others.
+
+This program and the accompanying materials are made
+available under the terms of the Eclipse Public License 2.0
+which is available at https://www.eclipse.org/legal/epl-2.0/
+
+SPDX-License-Identifier: EPL-2.0
+
+Contributors:
+    1C-Soft LLC - initial API and implementation
+```
+
+Если вы не являетесь сотрудником фирмы 1С - допишите актуальную информацию в секцию `Contributors:`
+
+Для всех новых или измененных файлов - выполняйте обновление копирайта: ПКМ по файлу - "Fix Copyrights".
+
+
+### Язык проекта
+
+Исходный код должен быть написан на Английском языке. Английский язык - является языком по умолчанию. 
+Не допускается использование транслита или иных не английских слов и терминов. 
+В случае, если вы затрудняетесь в выборе подходящего термина на английском - обратитесь за помощью в issue по вашей функциональности к владельцам проекта - мы всегда поможем!
+
+Язык ведения проекта (issue, аудит и т.д.) - Русский, т.к. ориентация на русское сообщество программистов. 
+Поддержка разработчиков на других языка в будущем может быть решена дополнительно.
+
+Все интерфейсные тексты должны быть написаны на английском яызке и локализированы - вынесены в отдельные ресурсные файлы `*.properties`. 
+Все локализируемые ресурсные файлы должны быть переведены на дополнительный русский язык.
+
+Например:
+
+- `messages.properties` - основной интерфейс, должен содержать английский интерфейс
+- `messages_ru.properties` - дополнительный интерфейс на русском языке
+
+
+Для большего удобства используйте помощник Eclipse Externalize Strings Wizard, который помогает переносить интерфейсные строки в ресурсные файлы.
+
+### Code Style
+
+Необходимо использовать `1C:EDT Code style` из поставки JDT для разработки плагинов 1C:EDT из программы установки и запуска 1C:EDT Start.
+
+
+### Документация не опциональна
+
+При добавлении новой функциональности или изменении существующей - необходимо актуализировать [документацию](/docs).
+
+### Тесты не опциональны
+
+Для каждой функциональности необходимо писать JUnit 4 тесты.
+
+Тесты должны включать в себя все варианты правильного и неправильного поведения системы, начальных условий.
+
+Не следует тестировать поведение 1C:EDT, но только лишь поведение кода текущего проекта.
+
+### Версионирование проекта
+
+В проекте используется семантическое версионирование [https://semver.org/lang/ru/](https://semver.org/lang/ru/)
+
+Текущая версия проекта "0" (еще нет "мажорного релиза"), это позволяет нам делать любые несовместимые изменения в каждой новой минорной версии.
+Это так же связано с тем, что многие части API в таргет-платформе 1C:EDT еще не стабилизированы и часто меняются.
+
+При этом, каждая минорная версия до первой мажорной - является полноценным релизом, готовым к использованию в проде.
+
+
+Дополнительно следует изучить про версионирование в  Eclipse:
+
+
+[https://wiki.eclipse.org/Version_Numbering](https://wiki.eclipse.org/Version_Numbering)
+
+[https://wiki.eclipse.org/Platform-releng/Incrementing_Version_Numbers](https://wiki.eclipse.org/Platform-releng/Incrementing_Version_Numbers)
--- a/Check_Convention.md
+++ b/Check_Convention.md
@ -0,0 +1,208 @@
+# Check convention - Соглашения проверок
+
+
+## Регистрация проверки
+
+### Категория проверки
+
+Проект 1С:Стандарты разработки V8 поставляет категории в разрезе типов объектов в метаданных.
+Следует указывать категорию для каждой проверки из соответствующего бандла, где размещен класс проверки.
+
+### Код проверки
+
+1. Cebab-case (кебаб-кейс) - с маленькой буквы, без пробелов, использовать тире между словами. Не следует использовать `CamelCase` т.к. он менее читабильный.
+2. Префикс типа объекта (md, form, right, ql, dcs и т.д) - код должен содеражть префикс типа объекта или имя уникального класса объекта (`common-module`, `catalog`, `role` и т.д.) что бы не допустить неоднозначности толкования к чему применяется проверка
+3. Преффикс вендора (`v8codestyle`) в коде проверки не используется
+4. Константа с кодом проверки должна быть приватной
+
+#### Код проверки должен отражать смысл проверяемой проблемы.
+
+Следует отражать в коде проверки находимую проблему или группу проблем (если проверка выполняет множество однотипных проверок).
+
+Не следует отражать в коде проверки - только лишь имен найденных объектов.  
+
+НЕПРАВИЛЬНО:
+
+Здесь ключ проверки отражает только имена объектов которые проверяет:
+```
+module-method-check
+function-type-check
+```
+
+
+Не следует в коде проверки отражать процесс поиска проблемной ситуации.
+
+НЕПРАВИЛЬНО:
+
+```
+check-method-usage
+```
+
+ПРАВИЛЬНО:
+
+```
+method-never-used
+```
+
+#### Код проверки должен корректно читаться вместе с аннотацией
+
+Это чуть более атуально для проверок по модулю - т.к. это будет везде визуально читаться.
+
+Для других типов проверок (по метаданным) аналогичное правило подходит, хоть и не будет постоянно отображаться везде в интерфейсе (при открытии доп.формы).
+
+НЕПРАВИЛЬНО:
+
+```bsl
+//@skip-ckeck check-method-never-used
+```
+
+ПРАВИЛЬНО
+
+```bsl
+//@skip-ckeck method-never-used
+```
+
+#### Слова-паразиты
+
+Следует избегать использования "слов-паразитов" которые не добавляют никакого смысла в код проверки, например слова: check, error, warning, артикли a, the, to, is, are и т.д. problem, valid
+
+НЕПРАВИЛЬНО
+
+```
+check-method-is-empty
+to-find-my-awesome-problem
+```
+
+ПРАВИЛЬНО:
+
+```
+method-empty
+awesome-problem
+```
+
+#### Разделение по типам объектов метаданных
+
+Из кода проверки желательно сразу понимать к какому типу объектов она имеет отношение. Обычно это следует от типа ТОП-объектов (md, form, module/bsl, dcs, ql, moxel).  Если проверка диагностирует проблему в подчиненном объекте имя которого уникально - можно не указывать префикс топ-объекта.
+
+НЕПРАВИЛЬНО:
+
+```
+attribute-type-empty
+parameter-name-too-short
+```
+
+ПРАВИЛЬНО:
+
+```
+form-attribute-type-empty
+md-attribute-type-empty
+method-parameter-name-too-short
+form-parameter-name-too-short
+module-standard-regions
+function-has-no-return-type
+```
+
+### Наименование проверки
+
+- Что проверяем, какую ошибку находит
+- Существительное, в именительном падеже
+
+
+### Детальное описание
+
+1. Следует указывать описание при регистрации проверки в классе.
+2. Формируется описание в виде `check.descriptions/check-id.md` и `check.descriptions/ru/check-id.md` с детальным описанием
+3. Ссылку на стандарт следует указывать в секции "См."
+4. Следует описывать все возможные варианты `НЕПРАВИЛЬНО` и `ПРАВИЛЬНО` которые находит проверка. Желательно использовать примеры из тестов.
+
+### Тип (issueType)
+
+Тип найденной диагностики
+
+- `ERROR` - Ошибка в приложении
+- `WARNING` - Предупреждение о проблеме в приложении
+- `SECURITY` - Уязвимость в приложении
+- `PERFORMANCE` - Проблема производительности приложения
+- `PORTABILITY` - Проблема универсальности метаданных и кода приложения.
+- `LIBRARY_DEVELOPMENT_AND_USAGE` - Проблема внедрения библиотеки или нарушение принципов библиотечной разработки.
+- `CODE_STYLE` - Соглашения при написании кода, некачественный код
+- `UI_STYLE` - Проблема проектирования UI
+- `SPELLING` - Опечатка в тексте, коде, в именах метаданных
+
+### Критичность (severity)
+
+Необходимо установить критичность найденной ошибки по умолчанию.
+Критичность необходимо устанавливать адекватную проблеме уровню проблемы в приложении.
+
+- `BLOCKER` - ошибку необходимо исправлять немедленно
+- `CRITICAL` - Критичная проблема, необходимо исправлять в первую очередь
+- `MAJOR` - Обычная проблема, исправлять следут в обычном порядке
+- `MINOR` - Незначительная проблема
+- `TRIVIAL` - Тривиальная проблема
+
+### Сложность (complexity)
+
+- `NORMAL` - Сложность алгоритма поиска ошибочной ситуации низкая, не выполянется обращение к объектам из других ресурсов.
+- `COMPLEX` - Большое количество вычислений, обращение к объектам из других ресурсов
+
+
+### Параметры
+
+Принципы создания параметров:
+- Возможность внести исключения в правило поиска проблемных мест
+- Нет смысла в параметрах если проверяется единственный объект и какое-либо исключение равно отключению проверки
+- Используйте паттерны в параметрах для поиска исключений
+- Любые значения (текстовые, числовые, с большой вариабельностью, кроме Булево) следует задавать через параметры
+
+Типовые примеры:
+- Исключение по имени метаданного
+- Длина, количество символов и т.д. - числовые значения в проверке обычно являются кандидатами для вынесения в параметры
+
+Соглашения при создании параметров:
+1. имена параметров должны быть понятны в контексте проверки
+2. имена параметров пишутся в `CamelCase`, с маленькой буквы
+3. Константа с именем параметра должна быть публичной
+
+
+## Логика проверки / код проверки
+
+- В общем случае, при регистрации проверки, следует выбирать тот объект, в котором будет найдена ошибка, от этого объекта следует вычислять/находить другие зависимые, влияющие объекты.
+- Код поиска ошибочной ситуации следует строить максимально оптимальным способом.
+- Не следует ухудшать читаемость кода, за исключением производительности.
+
+### Текст ошибки
+
+1. В чем ошибка
+2. Формат текста: существительное, именительный падеж 
+2. Указание значений параметров в сообщении
+
+Примеры:
+1. Переменная не была инициализирована
+2. Конфигурация содержит некоректный режим блокировки данных
+3. Метод пустой
+4. Метод не используется
+5. Длина имени объекта метаданного должна быть меньше чем `80`
+
+### Как проверять
+
+1. Одна проверка должна находить одно проблемное место в одном типе объектов
+2. Учитывать параметры, а не хардкод конкретных значений
+3. Учитывать исключения, место проверки исключения следует выбирать из оптимальности алгоритма
+
+При регистрации проверки, следует указывать все фичи от которых зависит логика проверки - это означает, что при изменении любого из второстепенных свойств объекта будет выполнена перевалидация по текущей проверке.
+
+## Тестирование проверок
+
+1. Для каждого варианта ошибочного состояния необходим тест, если тестовые ситуации слишком разные желательно различные тесты
+2. Для корректного состояния необходимо добавить тест, в котором проверка не должна находить проблему.
+
+Каждый корректный и ошибочный вариант должны быть добавлены в разделы "ПРАВИЛЬНО" и "НЕПРАВИЛЬНО" описания проверки
+
+
+## Проверка не по стандарту
+
+Если какая-либо проверка напрямую не описана в одном из стандартов, но при этом является полезной - такую проверку можно размещать в этом проекте.
+
+Проверку следует регистрировать по умолчанию выключенной - таким образом каждый проект 1С:Предприятия может сам решить какие дополнительные проверки активировать.
+
+Регистрация проверки не по стандарту, включенной по умолчанию, следует явно описывать в задаче (issue) в проекте, если контрибьютор считает, что ее необходимо активировать всегда.