Migration of Outstanding Best Practices issues and PRs #421
Description
TL;DR
- As GTFS Best Practices (BP) are being migrated to the specification, a number of outstanding Issues and PRs proposing changes to the Best Practices still exist and remain unresolved.
- MobilityData has carried out an initial evaluation of the status for each item and prepared a summary of all of these proposed changes.
- With this issue, we’re hoping to bring visibility to these outstanding issues and to restart the discussion around them, so that any improvement that the community finds valuable could be carried forward.
Context
- MobilityData has initiated a process to merge GTFS best practices into the official spec. This is intended to bring more visibility and adoption to existing and future best practices, based on feedback from the community.
- As of December 2023, multiple portions of the GTFS Schedule Best Practices have been successfully incorporated into the spec’s reference document with more coming soon as outlined in this phasing plan.
- Simultaneously, once adopted in the specification, every best practice transferred is removed from the Best Practices thus the Best Practices repositories (Schedule and Real Time) will eventually be deprecated.
- We suggest that discussions for changes to existing best practices or new ones take place in the google/transit repository. This change has already been implemented since earlier this year, with a notice redirecting community members to suggest changes for BP directly in the google/transit repo.
- Currently, there are several open Best Practices Issues and PRs both for Schedule and Real Time. The purpose of this issue is to transfer these outstanding items into the google/transit repository.
Outstanding Best Practices issues & PRs
Real Time
| Item | Description | Still relevant? | Status | Priority |
|---|---|---|---|---|
| Best Practices suggestions #2 | Include Route_id in trip update, vehicle position and alert feeds. Include vehicle position at all times. Include trip updates for at least an hour in the future | Yes | Further discussion needed | Low |
| Additional items to triage for best practices or spec inclusion #5 | Long list of best practices to be incorporated | Yes | Further discussion needed | Low |
| suggestion: serve GTFS-RT feeds with CORS enabled #16 | Enable cross-origin resource sharing for GTFS | Yes | Further discussion needed | Low |
| Proposed best practice: including trip_id in TripDescriptor #22 | Make trip_id matching in TripDescriptor recommended | Yes | Relatively simple change, can be moved to PR stage with a proposal depending on community interest | High |
| Recommend plain text output in addition to protobuf #17 | Recommend adding human readable text when debugging | Yes | Further discussion needed | Low |
| WIP: Add Schedule Changes section #21 | Provide general guidance on how to address schedule changes in RT | Yes | Further discussion needed | Low |
Schedule
| Item | Description | Still relevant? | Status | Priority |
|---|---|---|---|---|
| Also reference in-seat (block) transfers recommendation under trips.txt? #4 | Duplicate clarification text regarding the use of block_id in trips.txt | Yes | Relatively simple change, can be moved to PR stage with a proposal depending on community interest | High |
| Should stop locations be required to be unique? #6 | Quality-of-life change linked with validator: Specify that two stop records (in same dataset) should not overlap | Yes | Relatively simple change, might need further review re validator and impact on other parts of the specification | Low |
| calendar.txt and stop_id as stop_code #7 | Two changes: stop_code as recommended, unique calendar dates & continuous service dates | Yes | Further discussion needed | Low |
| Reliable wheelchair accessibility #32 | Provide additional guidance to guarantee adequate indication of wheelchair accessibility | Yes | Further discussion needed | Low |
| Proposed best practice: Include tts_stop_name when stop name is potentially unintelligible using TTS technology #34 | stops.tts_stop_name recommended when stop name is unintelligible by TTS technology | Yes | Relatively simple change, can be moved to PR stage with a proposal depending on community interest | High |
| Proposed Need: Articulating "redirects" from merged feeds #43 | Provide a solution for noting feeds that have been merged | Yes | Further discussion needed | Low |
| Best Practice and spec alignment #45 | Multiple small fixes and changes to align BP and the Spec | Partially | Some progress already done with the recent BP merge into the Spec, most of it is yet to be addressed | Low |
| Proposed Best Practice: Update practice for publishing future service #48 | Provide further guidance on merge practices and old vs new data | Partially | Some progress already done with the inclusion of the merge tools reference in the spec | Low |
| Update Best Practices with additional transfer types #51 | Add BP for transfer types: 4 & 5 | Yes | Relatively simple change, can be moved to PR stage with a proposal depending on community interest | High |
| DONE |
Make shape.txt recommended (Issue 37) | |||
| Add BP for consistency in trip route and direction ids with Realtime #40 | Consistency in references between static and RT | Yes | Relatively simple change, can be moved to PR stage with a proposal depending on community interest | High |
| Proposed one year cap to feed_end_date #42 | Add feed_info.feed_end_date recommendation to be less than a year from start_date | Yes | Further discussion needed | Low |
| Maintain persistent trip_id across data iterations as a best practice #49 | Recommend maintaining IDs across datasets in the future | Yes | Further discussion needed | Low |
| Make bikes_allowed a recommended field for all travel modes. #56 | Make bike_allowed field recommended in all cases | Yes | Relatively simple change, can be moved to PR stage with a proposal depending on community interest | High |
Issues and PRs no longer relevant
- Out of a total of 26 outstanding items, we have identified 6 which are no longer relevant, either because they will be (or already are) addressed with the migration of BP into the spec, or due to their presence at both the issue and PR stages (thus keeping only the PR as still relevant). The 6 issues deemed not relevant are listed below.
- [Real Time] - Add link to GTFS Resource and GTFS Realtime Specification #9
- [Real Time] - Increase navigability by adding links within about.md #10
- [Real Time] - [Formatting] Consolidate Best Practices into single legible document #18
- [Real Time] - Re-organize to add webpage rendering + nest files #20
- [Schedule] - Proposed best practice: shapes.txt should be included #37
- [Schedule] - Versioning cadence #41
Expected next steps
- MobilityData will post a message referencing this issue and the migration process in each of these outstanding Issues and PRs and then close them. They will remain visible to the community for reference.
- Acknowledging that addressing all these issues requires extensive community discussions, MobilityData will gradually work towards resolution, prioritizing based on needs.
- Community members are welcome to carry some of these issues forward by opening an issue or a PR on this repo. MobilityData will support any initiatives by helping to manage the discussions and provide technical support when needed.
As mentioned in previous issues dealing with this migration, MobilityData recognizes that this is a big effort that requires a great deal of community support and discussion, thus we welcome all contributions and we’re more than happy to provide our support to the community to move this forward.