v8-code-style/CONTRIBUTING.md

# Участие в проекте 1С:Стандарты разработки V8

Вначале, хотим поблагодарить Вас за желание участвовать в проекте!

Далее описаны советы, как сделать свое участие наиболее эффективным для проекта и для себя. 
Будьте благоразумны, если что-либо здесь не описано.

## У меня есть вопрос

1. Для начала убедитесь, что ответа нет в самой 1C:EDT.
2. Поищите информация в документации проекта

**Вопрос есть, но ответа не нашел?** Создай `issue`  

## Что я должен знать прежде чем начать

Изучите текущую функциональность проекта, цели проекта, где находится граница возможностей плагина и 1C:EDT.

Вопросы, которые не относятся к разаботке приложений в 1C:EDT по стандартам 1С, следует задавать в профильных сообществах.

## Сообщить об ошибке

Печально, что ошибка существует, но мы благодарны, что вы о ней нам сообщите!

#### Прежде чем зарегистрировать ошибку

* Проверьте [Docs](https://github.com/1C-Company/v8-code-style/docs/) на наличие описания, что не является ошибкой
* Проверьте раздел [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`. 

Кодировка файлов  `*.properties` - UTF-8.

Все локализируемые ресурсные файлы должны быть переведены на дополнительный русский язык.

Например:

- `messages.properties` - основной интерфейс, должен содержать английский интерфейс
- `messages_ru.properties` - дополнительный интерфейс на русском языке

В проекте используется система локализации **Eclipse NLS**:

- Необходимо создавать final-класс наследник `org.eclipse.osgi.util.NLS`
- В классе указывается консанта `BUNDLE_NAME` с полным квалификтором файла `messages` в котором хранятся локализованные сообщения.
- Создаются публичные константы, которые являются ключами в ресурсных файлах

```java
final class Messages
    extends NLS
{
    private static final String BUNDLE_NAME = "com.e1c.v8codestyle.md.check.messages"; //$NON-NLS-1$
    public static String CommonModuleNameClient_description;
    public static String CommonModuleNameClient_message;
    static
    {
        // initialize resource bundle
        NLS.initializeMessages(BUNDLE_NAME, Messages.class);
    }

    private Messages()
    {
    }
}
```

Для большего удобства используйте помощник Eclipse Externalize Strings Wizard, который помогает переносить интерфейсные строки из кода в ресурсные файлы, с автоматическим созданием файла констант NLS.

Для редактирования ресурсных файлов следует использовать плагин из Маркет-плайса Eclipse: [ResourceBundle Editor](https://marketplace.eclipse.org/node/2628188) или аналогичны, позволяющий синхронно редактировать интерфейсы на нескольких языках, корректно учитывающий кодировку UTF-8.

### 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)