From 8baddfb9f947db0f053b4342e590522a71f47a64 Mon Sep 17 00:00:00 2001 From: Yuri Petrov <48598325+petrovyuri@users.noreply.github.com> Date: Wed, 25 Jun 2025 10:35:03 +0300 Subject: [PATCH] =?UTF-8?q?feat(rfc):=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2?= =?UTF-8?q?=D0=B8=D1=82=D1=8C=20=D1=80=D0=B5=D0=BA=D0=BE=D0=BC=D0=B5=D0=BD?= =?UTF-8?q?=D0=B4=D0=B0=D1=86=D0=B8=D0=B8=20=D0=BF=D0=BE=20=D1=83=D0=BF?= =?UTF-8?q?=D1=80=D0=B0=D0=B2=D0=BB=D0=B5=D0=BD=D0=B8=D1=8E=20=D1=81=D0=B3?= =?UTF-8?q?=D0=B5=D0=BD=D0=B5=D1=80=D0=B8=D1=80=D0=BE=D0=B2=D0=B0=D0=BD?= =?UTF-8?q?=D0=BD=D1=8B=D0=BC=D0=B8=20=D1=84=D0=B0=D0=B9=D0=BB=D0=B0=D0=BC?= =?UTF-8?q?=D0=B8=20=D0=B8=20=D1=84=D0=B0=D0=B9=D0=BB=D0=BE=D0=BC=20pubspe?= =?UTF-8?q?c.lock=20(#18)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: PetrovY --- tools/rfc/RFC-managing_generated_files.md | 30 +++++++++++++++++++++++ tools/rfc/RFC-managing_pubspec_lock.md | 25 +++++++++++++++++++ 2 files changed, 55 insertions(+) create mode 100644 tools/rfc/RFC-managing_generated_files.md create mode 100644 tools/rfc/RFC-managing_pubspec_lock.md diff --git a/tools/rfc/RFC-managing_generated_files.md b/tools/rfc/RFC-managing_generated_files.md new file mode 100644 index 0000000..cdb2f5f --- /dev/null +++ b/tools/rfc/RFC-managing_generated_files.md @@ -0,0 +1,30 @@ +### Управление сгенерированными файлами + +На проекте встречаются файлы, автоматически создаваемые инструментами генерации кода +(например, файлы с расширениями *.g.dart, *.freezed.dart, +а также файлы, связанные с protobuf и другими генераторами кода). +Необходимость контролировать такие файлы в репозитории вызывает ряд обсуждений. +См [issue](https://github.com/smmarty/flutter_team/issues/22). + +### Проблемы включения сгенерированных файлов в репозиторий + + 1. Частые изменения. Сгенерированные файлы могут автоматически обновляться даже при отсутствии изменений в исходном коде, что приводит к ненужным изменениям в репозитории. + 2. Конфликты при слиянии веток. Различия в таких файлах могут вызывать конфликты, которые не связаны с реальными изменениями, усложняя процесс работы над кодом. + 3. Усложнение кода при проверке. Изменения в автоматически сгенерированных файлах попадают в PR, затрудняя код-ревью. + 4. Недостоверность содержимого main. Нет гарантии, что в основной ветке всегда будут корректные версии сгенерированных файлов. + +### Проблемы при добавлении сгенерированных файлов в .gitignore + + 1. Необходимость предварительной генерации. При добавлении таких файлов в .gitignore для проверки кода в пайплайне необходимо добавлять этап генерации при каждом изменении в PR. + Это критично на крупных проектах, так как генерация файлов может занимать несколько минут. + 2. Неудобства для разработчиков. Разработчикам потребуется вручную генерировать файлы на локальной машине при каждом чекауте. + 3. Неактуальный код в main. Основная ветка без предварительно сгенерированных файлов станет неработоспособной, а сборка потребует добавления этапа генерации, что увеличит время и нагрузку на серверы. + +### Рекомендации: + + 1. Оставлять сгенерированные файлы в репозитории. + Это позволит сохранить работоспособность основного кода без необходимости постоянной генерации файлов на всех этапах. + При этом рекомендуется: + - Периодически актуализировать файлы в основных ветках; + - Контролировать конфликты при слиянии веток и исключать ненужные изменения в этих файлах. + 2. Обучение команды. Важно информировать команду о причинах хранения сгенерированных файлов в репозитории и о правилах работы с ними. \ No newline at end of file diff --git a/tools/rfc/RFC-managing_pubspec_lock.md b/tools/rfc/RFC-managing_pubspec_lock.md new file mode 100644 index 0000000..aa6e159 --- /dev/null +++ b/tools/rfc/RFC-managing_pubspec_lock.md @@ -0,0 +1,25 @@ +# Управление файлом pubspec.lock + +На проекте возникает необходимость определить стратегию работы с файлом pubspec.lock. +Данный файл может либо храниться в репозитории, либо быть добавлен в .gitignore. +Оба варианта имеют свои преимущества и недостатки, которые следует учесть. +См [issue](https://github.com/smmarty/flutter_team/issues/20) + +#### Аргументы за хранение pubspec.lock + + 1. Повторяемость сборки. Файл фиксирует конкретные версии зависимостей, обеспечивая единообразие версий для всех разработчиков и сред сборки. + 2. Избежание неожиданных изменений. Новые версии зависимостей могут внести изменения, способные нарушить сборку или логику приложения. Наличие pubspec.lock позволяет контролировать изменения и избегать неожиданных обновлений. + 3. Стабильность CI/CD. Зафиксированные версии зависимостей способствуют стабильным сборкам и тестам в CI-процессах. + 4. Рекомендации Dart. Dart рекомендует хранить pubspec.lock в репозитории для приложений, чтобы обеспечить стабильность окружения. (См. документацию.) + +#### Аргументы против хранения pubspec.lock + + 1. Частые изменения. pubspec.lock обновляется при каждом изменении зависимостей, что увеличивает количество коммитов и PR, связанных только с обновлением зависимостей. + +### Рекомендации: + + 1. ХРАНИТЬ pubspec.lock для ПРИЛОЖЕНИЙ. + 2. НЕ ХРАНИТЬ pubspec.lock ДЛЯ ПАКЕТОВ. + 3. Решение для переключаемых зависимостей (GMS/HMS). + При изменении зависимостей, таких как GMS/HMS, может возникать несовместимость версий. Flutter пока не поддерживает флаворы на уровне зависимостей pubspec (см. [Flutter issue #46979](https://github.com/flutter/flutter/issues/46979)), + поэтому рекомендуем хранить по дефолту GMS pubspec.lock как базовый.