|
| 1 | +## Migration Guide - Transition from active_period to communication_period and impact_period |
| 2 | + |
| 3 | +The GTFS-realtime `alert.active_period` was defined as *“Time when the alert should be shown to the user. If missing, the alert will be shown as long as it appears in the feed. If multiple ranges are given, the alert will be shown during all of them.”* |
| 4 | + |
| 5 | +There was an ambiguity in this definition where the “time when the alert should be shown to the user” can be construed both as: |
| 6 | +- Time when the user is informed of the alert. |
| 7 | +- Time when the service disruption resulting from the alert is in effect. |
| 8 | + |
| 9 | +To resolve this ambiguity, `communication_period` and `impact_period` are introduced. |
| 10 | +- `communication_period`: Time when the alert should be shown to the user strictly for informative reasons. |
| 11 | +- `impact_period`: Time when the services are affected by the alert. |
| 12 | + |
| 13 | +To ensure the implementation of the new fields while keeping backward compatibility and taking into consideration infrastructure costs, the community agreed to assign `active_period` as deprecated but allow it to coexist with `communication_period` and `impact_period`. |
| 14 | + |
| 15 | +This migration guide defines how to interpret the coexistence of all 3 fields together, and outlines steps for gradual migration into the new fields `communication_period` and `impact_period`. The goal is to convince producers and consumers to gradually start using `communication_period` and `impact_period` instead of `active_period`. |
| 16 | + |
| 17 | +## Producers |
| 18 | +For producers, you can continue having all 3 fields in the same alert. Try to specify `communication_period` and `impact_period` in as many alerts as you can, especially alerts with NO_SERVICE. |
| 19 | + |
| 20 | +**Do not duplicate alerts to separate active_period from the new fields!** Set one alert per actual service incident, you can specify `communication_period`, `impact_period` and `active_period`. |
| 21 | + |
| 22 | +Whenever an alert has `communication_period` and `impact_period` specified, it is recommended to not include `active_period` (it is already an optional field). |
| 23 | + |
| 24 | +To promote best practices, it is recommended to specify `communication_period` and `impact_period` together as much as possible. |
| 25 | + |
| 26 | +All of the following examples are valid. |
| 27 | + |
| 28 | +### The recommended option |
| 29 | + |
| 30 | +```` |
| 31 | +alert { |
| 32 | +“communication_period”: [{ "start": …, "end": … } ], ← Time when the user is informed of the alert. |
| 33 | +"impact_period": [ { "start": …, "end": … } ], ← Time when the service disruption resulting from the alert is in effect. Can be multiple time periods if the service disruption is recurring. |
| 34 | +... |
| 35 | +} |
| 36 | +```` |
| 37 | + |
| 38 | +### Other valid options that are not recommended |
| 39 | + |
| 40 | +```` |
| 41 | +alert { |
| 42 | +“active_period”: [{ "start": …, "end": … } ], |
| 43 | +“communication_period”: [{ "start": …, "end": … } ], |
| 44 | +"impact_period": [ { "start": …, "end": … } ], |
| 45 | +... |
| 46 | +} |
| 47 | +```` |
| 48 | + |
| 49 | + |
| 50 | +```` |
| 51 | +alert { |
| 52 | +“active_period”: [{ "start": …, "end": … } ], |
| 53 | +"impact_period": [ { "start": …, "end": … } ], |
| 54 | +... |
| 55 | +} |
| 56 | +```` |
| 57 | + |
| 58 | + |
| 59 | +```` |
| 60 | +alert { |
| 61 | +“active_period”: [{ "start": …, "end": … } ], |
| 62 | +“communication_period”: [{ "start": …, "end": … } ], |
| 63 | +... |
| 64 | +} |
| 65 | +```` |
| 66 | + |
| 67 | + |
| 68 | +```` |
| 69 | +alert { |
| 70 | +“active_period”: [{ "start": …, "end": … } ], |
| 71 | +... |
| 72 | +} |
| 73 | +```` |
| 74 | + |
| 75 | + |
| 76 | +```` |
| 77 | +alert { |
| 78 | +“communication_period”: [{ "start": …, "end": … } ], |
| 79 | +... |
| 80 | +} |
| 81 | +```` |
| 82 | + |
| 83 | + |
| 84 | +```` |
| 85 | +alert { |
| 86 | +“impact_period”: [{ "start": …, "end": … } ], |
| 87 | +... |
| 88 | +} |
| 89 | +```` |
| 90 | + |
| 91 | +It is suggested that you notify existing consumers (e.g., via a developer mailing list) that the use of `active_period` is being deprecated by a set deadline and that consumers should start using `commnication_period` and `impact_period` instead. This migration guide should be included, with an emphasis on the *"Consumer"* section. After the deadline passes, you can remove `active_period` entities from your feed and publish only the `commnication_period` and `impact_period`. |
| 92 | + |
| 93 | +## Consumers |
| 94 | + |
| 95 | +For consumers, you can interpret the fields based on their spec definition. |
| 96 | +- If `active_period` exists with `communication_period` and `impact_period`, **ignore `active_period`** and use the other two fields. |
| 97 | + |
| 98 | +- If `active_period` exists with `impact_period`, **ignore `active_period`** and do not interpret it as `communication_period`. |
| 99 | + |
| 100 | +- If `active_period` exists with `communication_period`, **ignore `active_period`** and do not interpret it as `impact_period`. |
| 101 | + |
| 102 | +- If `active_period` exists alone, then use it. |
0 commit comments