Skip to content

Latest commit

 

History

History
234 lines (152 loc) · 22 KB

CONTRIBUTING.md

File metadata and controls

234 lines (152 loc) · 22 KB
Raw

Участие в проекте 1C:SSL support for 1C:EDT

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

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

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

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

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

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

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

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

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

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

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

  • Проверьте Wiki на наличие описания, что не является ошибкой
  • Проверьте раздел 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 проекта SSL-support
  • Убедитесь, что модификация кода действительно исправляет ошибку, описанную в issue, и не привносит новую функциональность - новую функциональность следует делать отдельным issue и pull-request'ом.
  • Следуйте общим правилам Pull/merge request

Pull Requests (Merge Requests)

  • Создайте issue в проекте с описанием новой функциональности, желательно перед началом работы, чтобы исключить параллельную работу разных людей над одной задачей
  • Создайте ветку в своем форке с именем feature/issue-<Номер issue>-доп-название
  • Внесите изменения в конфигурацию или расширение
  • Создайте pull-request из своей ветки в ветку master проекта SSL-support
  • Укажите ссылку на 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. Все локализируемые ресурсные файлы должны быть переведены на дополнительный русский язык.

Например:

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

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

Code Style

Необходимо использовать Java conventions из поставки JDT

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

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

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

Для каждой функциональности необходимо писать 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