5 правил того, что делает отдельную задачу, и пример разбиения задачи Apache Beam на задачи.

Суть проблемы в том, чтобы отслеживать прогресс и этапы изменения. Поэтому мое правило состоит в том, чтобы иметь наименьшую возможную проблему, которая:

  • Работает и не ломается.
  • Можно резюмировать одним предложением.
  • Изменяет что-то на уровне выше кода.
  • Представляет ценность по крайней мере для одной заинтересованной стороны.
  • Проверено, если я хочу тесты на этом.

Проблемы с большими проблемами

Проблемы большего масштаба приносят следующие проблемы:

  • Чем дольше кодировать, тем ветки устаревают. Вы можете разделить такую ​​проблему на несколько ветвей, но это лишает смысла задачу, которая заключается в отслеживании этапов изменения.
  • Отзывы рецензентов отложены.
  • Больше итераций во время обзоров.
  • Сложнее слиться.
  • Привлекает рецензентов разной специализации.
  • Блокирует работу, которая от него зависит.
  • Слишком широкие сообщения фиксации, если вам нужно проверить историю строки позже.
  • Менеджерам сложнее увидеть статус.
  • Риск того, что работа будет прервана отпуском или больничным.
  • Разочарование перед развертыванием.

Давайте взглянем на одно изменение, чтобы понять, как правильно разделить его на задачи.

Пример изменения

В документацию Apache Beam включены образцы исполняемого кода:

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

Этот встроенный редактор представляет собой приложение Flutter, а веб-сайт вокруг него представляет собой статический HTML, сгенерированный из файлов Markdown процессором Hugo.

Начните с одной проблемы

Во-первых, вы хотите, чтобы всю эту работу можно было отслеживать в целом. Поэтому вы создаете проблему типа «Переключение языка во встроенном редакторе».

Даже на этом высоком уровне вы должны решить, что выходит за рамки. Как разработчики, команда должна предоставить эту функцию команде документации, но не внедрять ее повсюду. Поэтому мы решили встроить один экземпляр обновленного редактора и позволить другим обновлять остальную документацию.

Высокоуровневая декомпозиция

Этот вопрос высокого уровня отправляется на рассмотрение. На данном этапе мы решаем:

  • Оставьте переключатель языка в HTML, поскольку он должен соответствовать некоторым существующим переключателям и пользовательским настройкам.
  • Пусть один iframe с Flutter обслуживает все языки, чтобы избежать лишних iframe для экономии ресурсов.
  • Попросите внешний JavaScript вызвать postMessage для iframe, чтобы дать ему команду изменить язык.

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

Низкоуровневые проблемы

Когда план более высокого уровня согласован, мы определяем вопросы низкого уровня:

1. Поддерживайте несколько состояний в редакторе

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

Таким образом, редактор знает о разных языках. Если он может сохранить изменения в коде Java при переключении на Go и обратно на Java, это ценно само по себе, поддается проверке и квалифицируется как проблема.

С другой стороны, если бы у нас был только встроенный редактор, это изменение нельзя было бы хорошо изолировать.

2. Загрузка нескольких примеров кода с URL-адресом

iframe должен загрузить четыре образца при запуске. Мы передаем идентификаторы образцов в формате JSON в URL-адресе:

Это зависит от того, завершена ли предыдущая проблема. Это удовлетворяет всем 5 требованиям и заслуживает отдельной проблемы.

Мы пока не говорим о ленивой загрузке, потому что редактор все равно загружает все примеры с сервера при запуске (это находится на ранней стадии).

3. Переключение языка редактора с помощью сообщения JavaScript

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

Как это отдельная проблема, если она не видна без кода для отправки сообщений?

Он находится на границе JavaScript и Flutter. Даже если один застройщик делает и то, и другое, граница сама по себе порождает стороны, заинтересованные в изоляции. Это:

  • Тестеры.
  • Рецензенты. Код JavaScript и Flutter проверяется разными участниками Apache. Рецензент должен быть уверен, что вещи по ту сторону границы стабильны, поэтому в идеале они уже развернуты или хотя бы объединены. Кроме того, рецензент не хочет шума, когда один большой PR обновляется с изменениями, не относящимися к его компетенции.
  • DevOps. При развертывании измененного веб-сайта приложение Flutter уже должно иметь возможность обрабатывать сообщения. Так что его нужно развернуть раньше. И все развертываемое должно быть отдельной проблемой только потому, что оно делит многие вещи на «до» и «после».

Можем ли мы продолжить этот вопрос? Помимо уже запланированного изменения SDK, существуют и другие типы сообщений. Можем ли мы сделать анализатор сообщений отдельной задачей, а затем этот конкретный обработчик сообщений?

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

Другие сообщения и их парсеры обязательно будут выделены в отдельные задачи.

4. Шорткод для создания iframe редактора

Разработчики документации не встраивают фреймы. Вместо этого они пишут Markdown следующим образом:

В выделенной строке находится так называемый «шорткод». Это макрос процессора Hugo, который идет в Markdown и генерирует HTML. В частности, это то, как одноязычный редактор был встроен в документацию Beam.

Поэтому мы должны создать новые шорткоды, которые будут использоваться следующим образом:

Но у нас пока нет вкладок, которые могут отправлять сообщения для переключения. Без них результат совершенно не отличим от предыдущего одноязычного редактора. Единственное, что можно проверить, это то, что iframe создается с заданным URL-адресом для загрузки всех 4 образцов.

Этого как раз достаточно, чтобы претендовать на отдельную проблему.

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

Это действительно крайний случай. Поэтому мы пошли с отдельной проблемой, но затем сделали это в одном PR с переключателем. Это тоже нормально.

Это лучше, чем наоборот, с несколькими PR для одного выпуска. Каково состояние проблемы, если она только частично объединена? Это худший случай.

5. Отправка сообщений при переключении языка

У нас уже было языковое переключение для невыполнимого кода в документации Apache Beam:

Вот почему у нас не было отдельной проблемы для вкладок.

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

6. Вставьте пример экземпляра редактора с переключателем языка

Это отдельно от вышеперечисленного. Основная причина в том, что в этих двух частях заинтересованы разные стороны.

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

Даже этого достаточно, чтобы разделить два вопроса.

Связывание проблем

Вопросы низкого уровня могут быть созданы как подзадачи высокого уровня. При редактировании задачи добавьте список задач с помощью этой кнопки или просто набрав
- [ ]

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

И у вас появилась новая проблема:

Это оно.

Были ли у вас когда-нибудь проблемы из-за слишком больших или слишком маленьких задач?