Moving Schedule Best Practices into the Spec: Phasing Plan
- Dominant language
- No language data
- Stars
- 1.1k
- Forks
- 225
- Avg merge
- 7d 17h
- Merged PRs (30d)
- 3
Description
## Problem
Referenced from #375 and #376:
MobilityData’s heard a number of pains from the community about the GTFS best practices and the spec’s SHOULD statements living in two different places:
- Producers do not always refer to the best practices, and so moving these into the official spec would give the best practices greater visibility and improve data quality for everyone
- Merging the best practices in the spec would make it easier for regulators to point producers to one place to get the information they need to create their GTFS feeds
## Phasing Plan
Based on this feedback, MobilityData is interested in working to merge the best practices into the official spec. There’s notable community interest in this based on[ the successful adoption of a recommended presence in the spec.](https://github.com/google/transit/pull/386)
We recognize this is a big effort that will require much community discussion, so we want to propose clear phases to this work, suggested below. Each phase will include a corresponding PR on the [Best Practices repo](https://github.com/MobilityData/GTFS_Schedule_Best-Practices) to remove the rules that have been added to the spec. Any community members are welcome to open a PR to merge best practices — the goal of this phasing plan is for everyone to be roughly aligned on steps so anyone can move to action.
MobilityData commits to updating the [Best Practices repo](https://github.com/MobilityData/GTFS_Schedule_Best-Practices) to point new best practice discussion and PRs to https://github.com/google/transit, and add previous Best Practice issues to the spec repository.
Phase # | Best practice section | What’s included | Status
-- | -- | -- | --
1 | Recommended presence (PR #386) |
- Recommended presence
- Updated presence for universally recommended fields
2 | [Dataset Publishing and General Practices](https://gtfs.org/schedule/best-practices/#dataset-publishing-general-practices) & [All Files guidelines](https://gtfs.org/schedule/best-practices/#all-files) |
- Add Dataset Publishing guidelines as new section of the spec, with reference to https://gtfs.org/resources/gtfs/#gtfs-merge-tools instead of merge function in the old transitfeed validator
- Update spec File Requirements section to include All File guidelines
3 |[ Outstanding Practice Recommendations Organized by File](https://gtfs.org/schedule/best-practices/#practice-recommendations-organized-by-file) | All file recommendations unrelated to
- specific cases (loop routes, lasso routes, branches)
- calendar.service_name (requires adopting a new field)
4 | [Practice Recommendations Organized by Case](https://gtfs.org/schedule/best-practices/#practice-recommendations-organized-by-case) |
- Move table examples to https://gtfs.org/schedule/examples/
- For the sake of consistency, move blocks and service day table example to https://gtfs.org/schedule/examples/
- Move explicit recommendations into spec
- Include linked reference to gtfs.org examples section in the spec
5 | [Calendar.service_name](https://gtfs.org/schedule/best-practices/#calendartxt) | Adopt calendar.service_name. Will require a producer and consumer to state they’re implementing this. | TBD
6 | History on Best Practices Working Group | Relevant sections of the Best Practices [FAQ](https://gtfs.org/schedule/best-practices/#frequently-asked-questions-faq) and [About this Document](https://gtfs.org/schedule/best-practices/#about-this-document) will be added as a new section in https://gtfs.org/schedule/changes/ | TBD
## Outstanding Questions for Community
Are there phases you’d split up to be more granular? (The File Recommendations in particular come to mind). If so, which best practices may require more discussion or are higher priority?
Contributor guide
Assessment
This issue has not been assessed yet.