erlang-guidelines/contributing.md

Внесение изменений

Набор рекомендаций по процессу внесения изменений в исходный код проекта, будь то реализация новой функциональности, исправление багов или рефакторинг.

Рекомендации представлены в формате чеклистов, в которых перечислены пункты, на которые настоятельно стоит обратить внимание.

Все эти процессы тесно связаны и естевственным образом отражаются на подходе к работе с системой контроля версий.

Создание новой функциональности

• проработка предметной области и выделение основных абстракций;

• написание кода, реализующего эти абстракции;

  Следует предоставлять в модулях простые, понятные и полные (симметричные) интерфейсы.

  Огромное количество полезных рекомендаций приведено в соответствующем документе.

• покрытие написанного кода спеками;

  Хорошей практикой является покрытие типами и спеками элементов и процессов, присутствующих в предметной области.

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

• покрытие написанного кода тестами;

  Большее внимание стоит уделять тестам, затрагивающим исключительные, неуспешные или ошибочные сценарии использования нового функционала, и только потом – тестам успешных или штатных сценариев использования.

  Тесты должны быть самодостаточными, иными словами явно поддерживать настройку критичного для тестовых сценариев окружения, mocking или работу с эфемерными внешними зависимостями, будь то девственно чистые базы данных, пустые списки и правила контроля доступа или отсутствующие сервера доменных имён. В экстремальных случаях возможно даже отсутствие интернета на время запуска и прогона тестов.

  Необходимо отказаться в тестах от стохастического поведения, привнесения элемента случайности. Также не стоит использовать слишком большие, ничем не оправданные задержки. Каждая операция в тестовом сценарии должна иметь понятный и чётко определённый критерий завершения.

  Сценарии, опять же по возможности, должны быть написаны с расчётом на то, что они будут запускаться в экстремальном случае в параллельном режиме, одновременно и в случайном порядке.

  Если инструменты для тестирования дают такую возможность, следует давать тестам понятные разработчику названия и/или описания.

• написание документации;

  Если вносимое изменение каким-либо образом отражается на внешних интерфейсах сервиса, приложения или библиотеки (при решении бизнес-задач случается в 95% случаев), этот эффект должен быть отражён в документации.

  Если реализация задачи привела к появлению нового, отдельного сервиса, хорошей мыслью будет сразу написать к нему краткую операционную документацию. Вопросы, которые непременно будут волновать админов / операторов: установка, начальная настройка, запуск, проверка работоспособности и конечно же остановка.

  Чем ближе документация к репозиторию с кодом, тем лучше.

• подготовка процессов миграции.

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

  Также не лишним будет задокументировать последствия миграции.

Правка багов

• анализ ситуации, в которой наблюдается ошибочное поведение;

• написание одного или нескольких тестовых сценариев, покрывающих эти ситуации;

  Хорошим тоном будет сразу провести прогон тестов и проверить, что новые тестовые сценарии действительно завершаются неуспешно в отсутствии исправления.

• исправление логики в исходном коде.

  После этого все тестовые сценарии из предыдущего пункта должны завершатся успешно.

  Если в процессе исправления назревает необходимость в рефакторинге, рекомендуется его проводить в рамках отдельного процесса внесения изменений.

Напоминания в коде (TODO, FIXME, etc. )

• исправлены все BUG, TODO, FIXME и др., которые могут и должны быть решены в рамках текущей задачи

• все остальные требования действий проассоциированы с задачей/другим позывом к действию

  Следующая запись наверняка добавит ещё один TODO к списку тех, которые никогда не разрешатся, и (что ещё хуже) не даёт возможности понять, актуально ли ещё это:

  %% TODO: fix this as soon as we deploy FooBar feature
  

  Следующая же запись позволит (даже автоматизированно) проверить актуальность задачи и возможность приступить к ней:

  %% TODO(ED-1234): fix this as soon as we deploy FooBar feature (ED-999)
  

• другие заметки на тему производительности и других не критичных с точки зрения бизнес-логики вещей помечены тэгом без позыва к действию: HACK, NOTE, PERF, KLUDGE, XXX.