Moving Schedule Best Practices into the Spec: Phasing Plan

[emmambd]

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.

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 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 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	Adopted ✅
2	Dataset Publishing and General Practices & All Files guidelines	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	Adopted ✅
3	Outstanding 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)	TBD
4	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	TBD
5	Calendar.service_name	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 and 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?

[emmambd]

Curious if those who voted for #386 have any feedback on this plan: @gcamp, @markstos, @westontrillium, @derhuerst, @doconnoronca, @NomeQ, @evansiroky, @philip-cline, @bdferris-v2

[NomeQ]

We don't have any strong opinions on the phasing. It looks like a reasonable plan.

[markstos]

I agree with @NomeQ

[e-lo]

MobilityData commits to updating the Best Practices repo to point new best practice discussion and PRs to https://github.com/google/transit, and add previous Best Practice issues to the spec repository.

😻

And I really appreciate the thought that went into the phasing plan and the transparency that it provides. Bravo! 🙌

[bdferris-v2]

Phasing seems reasonable; I don't have strong opinions.