1c/v8-code-style
1
0
Fork 0
mirror of https://github.com/1C-Company/v8-code-style.git synced 2024-12-03 19:26:38 +02:00
Code Issues Releases Activity
334598af33
v8-code-style/CONTRIBUTING.md
Dmitriy Marmyshev bbd432868f #1 перенос правил контрибутинга
2021-05-21 14:19:41 +03:00

24 KiB
Raw Blame History

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

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

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

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

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

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

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

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

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

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

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

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

  • Проверьте Docs на наличие описания, что не является ошибкой
  • Проверьте раздел Issues, чтобы не создавать дубликатов

Как сообщить об ошибке эффективно

Следуйте простым правилам:

  1. Задайте понятный заголовок issue, лаконично и исчерпывающе определяющий проблему
    • постарайтесь не допускать двойного смысла, сленга из других областей и т.д.
    • Не используйте "метки" в заголовке - для этого используются метки (labels) на гитхабе
  2. Опишите сценарий воспроизведения ошибки.
    • скриншоты очень сильно помогают, но не заменяют сценарий
    • добавьте логи ЖР, из лог-файлов (убедитесь, что они не содержат приватной информации)
  3. Опишите, что есть ошибка по вашему мнению и почему
  4. Опишите ожидаемое поведение

Предложите улучшение функциональности

  1. Задайте понятный заголовок issue, лаконично и исчерпывающе определяющий новую функциональность
  2. Опишите суть улучшений и обсудите в issue варианты реализации.
  3. Убедитесь совместно с авторами проекта, что ваше предложение не противоречит идеологии Стандартов 1С и 1C:EDT. При этом авторы проекта всегда рады обсуждению новых идей, всегда на стороне участников, предлагающих улучшения, но при этом постараются максимально разъяснить случаи отказа в принятии идеи/реквеста, если таковые возникнут.
  4. Реализуйте Ваше улучшение функциональности проекта в отдельном форке и предложите его через Pull/merge request

Доработка кода

Написание проверок

См. Соглашение при создании проверок

Исправление ошибок

  • Создайте issue в проекте с описанием ошибки. Убедитесь, что владельцы проекта так же считают текущее поведение ошибочным.
  • Создайте ветку в своем форке с именем bugfix/issue-<Номер issue>-доп-название
  • Создайте pull-request из своей ветки в ветку master проекта v8-code-style
  • Убедитесь, что модификация кода действительно исправляет ошибку, описанную в issue, и не привносит новую функциональность - новую функциональность следует делать отдельным issue и pull-request'ом.
  • Следуйте общим правилам Pull/merge request

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, и указать причину ошибочного поведения, а так же, каким образом это исправили. Человек (или даже вы сами), который через пару лет наткнется на неочевидное изменение, скажет вам спасибо.

Количество коммитов

Стоит ли делать один коммит на фичу - зависит от фичи. Коммит - логически завершенное изменение, а сложная фича может содержать много таких изменений, слияние которых в один коммит, приводит к потере информации о деталях ее выполнения. Это касается не только фич.

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.

Все файлы проекта, подлежащие лицензированию, должны иметь заголовок.

/*******************************************************************************
 * 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

Добавьте в настройки согласно инструкции:

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 в котором хранятся локализованные сообщения.
  • Создаются публичные константы, которые являются ключами в ресурсных файлах
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 или аналогичны, позволяющий синхронно редактировать интерфейсы на нескольких языках, корректно учитывающий кодировку UTF-8.

Code Style

Необходимо использовать 1C:EDT Code style из поставки JDT для разработки плагинов 1C:EDT из программы установки и запуска 1C:EDT Start.

Документация не опциональна

При добавлении новой функциональности или изменении существующей - необходимо актуализировать документацию.

Тесты не опциональны

Для каждой функциональности необходимо писать JUnit 4 тесты.

Тесты должны включать в себя все варианты правильного и неправильного поведения системы, начальных условий.

Не следует тестировать поведение 1C:EDT, но только лишь поведение кода текущего проекта.

Версионирование проекта

В проекте используется семантическое версионирование https://semver.org/lang/ru/

Текущая версия проекта "0" (еще нет "мажорного релиза"), это позволяет нам делать любые несовместимые изменения в каждой новой минорной версии. Это так же связано с тем, что многие части API в таргет-платформе 1C:EDT еще не стабилизированы и часто меняются.

При этом, каждая минорная версия до первой мажорной - является полноценным релизом, готовым к использованию в проде.

Дополнительно следует изучить про версионирование в Eclipse:

https://wiki.eclipse.org/Version_Numbering

https://wiki.eclipse.org/Platform-releng/Incrementing_Version_Numbers