DRAFT: Add RT alerts guidance - #696
Conversation
| !!! Note | ||
|
|
||
| Prior to `communication_period` and `impact_period`, time periods for alerts were described using `active_period`, which was deprecated in [PR\#546](https://github.com/google/transit/pull/546) to resolve the uncertainty around its use. | ||
| Producers can still create `active_period` and consumers can still use it with the same general guidelines mentioned below for `communication_period` and `impact_period`. However, it is recommended to use `communication_period` and `impact_period` to make sure that the display time of the alert is distinct from when it comes into effect. |
There was a problem hiding this comment.
I have a thought on this piece: if we want people to switch over to Comm/Impact period instead of active period, I would remove this whole section and instead direct users to the migration guide. To me, it adds a bit more confusion, we're suggesting to change, but also saying it's deprecated (I know there's a bundle of nuance in all of this, but for someone who is reading this, they want to cut to the chase: which one am I supposed to use? So we should answer that.
There was a problem hiding this comment.
@abigailmbd I think the main objective is definitely to use communication/impact_period. That's the priority. However, it would also be great for the guide to be relevant to people who are not in that migration process yet or do not have the resources for it. So I am for linking to the migration guide. Nevertheless, I would love to keep the communication/impact_period section a "time period" section, i.e. "How do we deal with time periods in alerts?".
We could change the language to say that people should definitely be up-to-date with the spec and switch (with the link to the migration guide given), but I'd also like to say that if they cannot, they could still refer to this section for guidance.
Adjusted small details in intro.md
- Increased visibility of GTFS Schedule vs Realtime - Altered text for improved readability
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds a new “GTFS Realtime Service Alerts” guidance section to the docs, covering recommended practices plus examples and use-cases.
Changes:
- Adds an introduction and general guidelines for producing Service Alerts.
- Adds detailed real-world use cases and “real-life” alert examples with suggested improvements.
- Wires the new docs pages into the MkDocs navigation.
Reviewed changes
Copilot reviewed 5 out of 8 changed files in this pull request and generated 10 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/en/resources/mobilitydata-recommendations/gtfs-realtime-service-alerts/intro.md | Introduces the Service Alerts guidance and provides high-level context and links. |
| docs/en/resources/mobilitydata-recommendations/gtfs-realtime-service-alerts/guidelines.md | Adds recommended practices and field-level guidance (periods, informed entity, header/description, etc.). |
| docs/en/resources/mobilitydata-recommendations/gtfs-realtime-service-alerts/real-world-use-cases.md | Adds a curated list of Service Alerts use-cases with suggested templates and setup recommendations. |
| docs/en/resources/mobilitydata-recommendations/gtfs-realtime-service-alerts/real-life-examples.md | Adds real agency examples with critique and “improved alert” proposals. |
| config/en/mkdocs.yml | Adds the new “GTFS Realtime Service Alerts” section to site navigation. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
f1985bb to
a26a639
Compare
No description provided.