1
0
mirror of https://github.com/1C-Company/v8-code-style.git synced 2024-12-05 03:58:31 +02:00
v8-code-style/CONTRIBUTING.md

269 lines
24 KiB
Markdown
Raw Normal View History

# Участие в проекте 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)