Добавление новых полей в GTFS Realtime

Когда производитель или потребитель заинтересован в добавлении нового поля в спецификацию GTFS Realtime, они должны открыть новый вопрос в репозитории GTFS Realtime GitHub с описанием предлагаемого поля и объявить об этом новом поле (включая ссылку на вопрос) в списке рассылки GTFS Realtime.

Процесс внесения изменений в спецификацию

1. Создать ветку git с обновлением всех соответствующих частей определения протокола, спецификации и файлов документации (за исключением переводов).
2. Создайте запрос на поставку на сайте https://github.com/google/transit. Запрос на исправление должен содержать расширенное описание исправления. Создатель запроса становится его защитником.
3. После регистрации pull request'а он должен быть анонсирован его сторонником в списке рассылки GTFS Realtime. После анонса запрос считается предложением.
   • Поскольку защитник является соавтором, он должен подписать Лицензионное соглашение соавтора, прежде чем заявка будет принята.
4. Далее следует обсуждение этого предложения. В качестве единственного форума для обсуждения должны использоваться комментарии к Pull-запросам.
   • Обсуждение длится столько, сколько адвокат считает нужным, но должно быть не менее 7 календарных дней.
   • Адвокат отвечает за своевременное обновление предложения (т.е. pull request) на основе комментариев, с которыми он согласен.
   • В любой момент time защитник может заявить об отказе от предложения.
5. Адвокат может назначить голосование по версии предложения в любой момент времени после первоначального 7-дневного интервала, необходимого для обсуждения.
   • Перед призывом к голосованию, по крайней мере, один производитель GTFS-realtime и один потребитель GTFS-realtime должны реализовать предложенное изменение. Ожидается, что производитель (производители) GTFS-realtime включит изменение в общедоступный канал GTFS-realtime и предоставит ссылку на эти данные в комментариях к запросу, а потребитель (потребители) GTFS-realtime предоставит в комментариях к запросу ссылку на приложение, которое использует изменение нетривиальным образом (т.е. поддерживает новую или улучшенную функциональность).
   • Призывая к голосованию, сторонник должен четко указать, идет ли речь об официальном принятии поля в спецификацию или об экспериментальном поле.
6. Голосование длится минимальный период, достаточный для того, чтобы охватить 7 полных календарных дней и 5 полных швейцарских рабочих дней. Голосование заканчивается в 23:59:59 UTC.
   • Сторонник должен объявить конкретное время окончания голосования в начале голосования.
   • В период голосования разрешены только редакционные изменения предложения (опечатки, формулировки могут быть изменены, если это не меняет смысла).
   • Любой желающий может проголосовать "да/нет" в форме комментария к pull request, и голоса могут быть изменены до конца периода голосования. Если голосующий меняет свой голос, рекомендуется сделать это, обновив первоначальный комментарий к голосованию, зачеркнув его и написав новый голос.
   • Голоса, поданные до начала периода голосования, не учитываются.
7. Предложение принимается, если за него единогласно проголосовало не менее 3 человек.
   • Голос автора предложения не учитывается при подсчете 3 голосов. Например, если автор предложения X создал запрос на исправление и проголосовал "за", а пользователи Y и Z проголосовали "за", это считается как 2 голоса "за".
   • Голоса против должны быть мотивированными и в идеале предоставлять действенную обратную связь.
   • Если голосование провалилось, то сторонник может продолжить работу над предложением или отказаться от него. Любое решение сторонника должно быть объявлено в списке рассылки.
   • Если сторонник продолжает работу над предложением, то новое голосование может быть назначено в любой момент времени.
8. Любой запрос на доработку, остающийся неактивным в течение 30 календарных дней, будет закрыт. Когда запрос закрыт, соответствующее предложение считается заброшенным. Сторонник может в любое время снова открыть запрос, если он хочет продолжить или поддержать разговор.
   • Обратите внимание, что сторонник может решить реализовать функцию как пользовательское расширение, а не как часть официальной спецификации.
9. Если предложение принято:
   • Google обязуется объединить проголосованную версию запроса на исправление (при условии, что участники подписали CLA, и выполнить запрос на исправление в течение 5 рабочих дней.
   • Google обязуется своевременно обновлять репозиторий https://github.com/google/gtfs-realtime-bindings. Коммиты в gtfs-realtime-bindings, которые являются результатом предложения, должны ссылаться на запрос на исправление предложения.
   • Переводы не должны включаться в исходный запрос на пополнение. Google несёт ответственность за обновление соответствующих переводов на поддерживаемые языки, но чистые запросы на перевод от сообщества приветствуются и будут приняты, как только будут устранены все замечания редакции.

Экспериментальные поля

1. Если сообщество сможет прийти к консенсусу (a) о том, что предлагаемое поле кажется полезным, и (b) о типе поля (optional или repeated, string или int или bool), то номер поля будет присвоен в сообщении GTFS Realtime, а в файле .proto и документации будет сделана пометка, что это экспериментальное поле, которое может измениться в будущем.
   • Консенсус достигается через процесс обсуждения и голосования, который аналогичен процессу внесения поправок в Спецификацию, но вместо единогласного согласия для утверждения требуется только 80% голосов "за".
   • Производители и потребители GTFS Realtime, желающие использовать новое экспериментальное поле, должны перегенерировать свои библиотеки, используя файл .proto с новым полем (например, Google обновит библиотеку gtfs-realtime-bindings), и начать заполнять и анализировать поле с помощью живых данных.
   • Как только мы убедимся, что экспериментальное поле оправдывает себя, а производители и потребители используют его, мы выполним описанный ниже процесс внесения поправок в спецификацию, чтобы официально добавить поле в спецификацию.
   • Если экспериментальное поле не будет принято через процесс внесения поправок в Спецификацию в течение 2 лет после утверждения в качестве экспериментального поля, оно будет деприватизировано путем добавления [deprecated=true] рядом со значением поля в файле .proto. Используя [deprecated=true] (вместо RESERVED), производителям и потребителям, которые уже приняли поле, не придется исключать его из использования. Кроме того, поле может быть "снято с использования" в будущем, если оно будет одобрено в ходе последующего голосования после процесса внесения поправок в Спецификацию (например, когда дополнительные производители и/или потребители начнут использовать поле).
2. Если новое поле считается специфическим для одного производителя или существует спор по поводу типа данных, то мы назначим производителю пользовательское расширение, чтобы он мог использовать поле в своем фиде. По возможности мы должны избегать расширений и добавлять поля, полезные для многих агентств, в основную спецификацию, чтобы избежать фрагментации и дополнительной работы для потребителей по поддержке различных расширений спецификации.

Руководящие принципы

Для того чтобы сохранить первоначальное видение GTFS Realtime, был установлен ряд руководящих принципов, которые следует учитывать при расширении спецификации:

Feeds должны быть эффективными для производства и потребления в реальном времени.

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

Эта спецификация касается информации о пассажирах.

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

Изменения в спецификации должны быть обратно совместимы.

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

Спекулятивные функции не приветствуются.

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

История пересмотра

12 марта 2020 г.

• Обновлено описание TripDescriptor на справочной странице GTFS Realtime.

26 февраля 2015 г.

• Добавлено экспериментальное поле direction_id в TripDescriptor(обсуждение).

30 января 2015 г.

• Добавлено пространство имен расширения Protocol Buffer ко всем оставшимся сообщениям GTFS-realtime, которые еще не имели его (например, FeedMessage и FeedEntity).

28 января 2015 г.

• Добавлено экспериментальное поле delay в TripUpdate(обсуждение).

16 января 2015 г.

• Обновление описания TripDescriptor.start_time.

8 января 2015 г.

• Определено экспериментальное перечисление OccupancyStatus.
• Добавлено экспериментальное поле occupancy_status в VehiclePosition(обсуждение).

22 мая 2014 г.

• Обновлено описание перечисления ScheduleRelationship в сообщении StopTimeUpdate(обсуждение).
• Удалено REPLACEMENT из значений перечисления ScheduleRelationship в сообщении TripDescriptor(обсуждение).

12 октября 2012 г.

• Добавлено поле временной метки в сообщение TripUpdate.

30 мая 2012 г.

• В спецификацию добавлены подробности о Расширениях.

30 ноября 2011 г.

• Добавлено пространство имен расширения Protocol Buffer к ключевым сообщениям GTFS-realtime, чтобы облегчить написание расширений к спецификации.

25 октября 2011 г.

• Обновлена документация, чтобы уточнить, что alert, header_text и description_text являются обычными текстовыми значениями.

20 августа 2011 г.

• Обновлена документация для уточнения семантики сообщения TimeRange.

22 августа 2011 г.

• Первоначальная версия.