Remove Best Practices already covered by the spec#44
Conversation
Redundant with specification description: "Should be provided to help GTFS consumers choose capitalization rules and other language-specific settings for the dataset."
Redundant as the specification indicates stop_id must be a Unique ID
Already described in "Data Publishing & General Practices" section.
Already defined by the specification: "The stop_name should match the agency's rider-facing name for the location as printed on a timetable, published online, or represented on signage. For translations into other languages, use translations.txt."
Already defined under "All Files" section
Already defined under "All Files" section
Covered by the spec, and "must" requirements are not allowed in best practice (recommendation) documentation.
Usage of fields is covered by the spec
Usage of fields is covered by the spec
Already covered by the spec in "Field Types" section: "An ID field value is an internal ID, not intended to be shown to riders"
Covered by the spec (duplication)
Covered by the spec (duplication)
Usage recommendation already covered by the spec: "Recommended: Use calendar_dates.txt in conjunction with calendar.txt to define exceptions to the default service patterns defined in calendar.txt. If service is generally regular, with a few changes on explicit dates (for instance, to accommodate special event services, or a school schedule), this is a good approach. In this case calendar_dates.service_id is a foreign ID referencing calendar.service_id."
Remove BP for a field that does not exist in the file
|
I just wanted to note that I really appreciate this type of clean-up work. 🙌 Thank you! |
|
+1 |
|
+1 Transit |
|
Thanks to all who voted. We needed a minimum of 3 votes to process an outcome for this PR, but only got 2. Since there were no -1s, let's extend the voting period another week. Voting ends 2022-01-24 at 23:59:59 UTC. Thanks! |
|
This is a great start, but as an organization which needs to provide clear guidance on what needs to be followed, this does cloud/add complexity which I'd like to resolve (or have a clear path to resolving with a commitment to deliver) before approving. User story I'd like to resolve: As a regulator*, I'd like to point to clear requirements for transit providers' data satisfying the GTFS Specification and GTFS Best Practices This proposal adds complexity in that you have to look at the spec, some (all?) of the spec's "usage recommendations", and the best practices. |
|
@e-lo This PR aims to limit the amount of redundant information scattered across different pieces of documentation. Thus actually reducing complexity and increasing the quality of overall documentation on GTFS. Whatever the case may be for how the spec or other pieces of best practice documentation are leveraged by regulators to get agencies to comply seems off-topic here IMHO. I.e.,
This is up to you. Different regulators may have different standards that yield different configurations of how documentation is used. For example:
Given the "clean-up" nature of the PR, how does this PR in particular change the nature of how you are doing things now? Keep in mind that this PR is a step in migrating suitable Best Practices into the spec. An excerpt from the FAQ section:
Additionally, an updated and centralized documentation platform is in the works so that these pieces of documentation will be accessible one place. |
|
If this PR passes, we would need to update our requirements to the third option you mentioned:
I am not opposed to having a requirement like this in the interim, but long-term, it is quite onerous for users to check several places for what they should be doing. The "anticipation of" the best practices becoming SHOULDs in the spec isn't really something I trust and I'd love more of a full commitment to making this the reality in the near-term. |
What are your current requirements? I think I'm missing something and I'd like to understand how consolidating redundant information affects your party.
Agree. Since the launch of the Best Practices, checking 2 places has been the state of affairs for regulators wishing to do so. This is why we are in the piece-wise process of migrating Best Practices into the spec as "SHOULDs". Getting rid of redundancies is an important step to gain clarity on this migration.
I agree the process has been informal. Is your trust a question of roadmapping/visibility of the process? If so I'll cc @Cristhian-HA. Nonetheless, here we have a very real PR working towards this goal. In terms of trust, I'd also like to highlight the great community accomplishment to update GTFS Schedule to RFC 2119 merged just under 5 months ago, and demonstrable examples (1, 2) of Best Practice-to-spec migration (of which I'm sure we'll see more of from the open source community). |
|
Our v2.0 CA Minimum GTFS Guidelines have the following language:
We would need to do a point-update of the guidelines to v2.1 to read something like:
I think this probably reads clearer w.r.t. our intent anyways – but would appreciate any thoughts! |
Yes, I'd appreciate a roadmap documenting the timeline. I feel like this has been on the "to do" for months/years and appreciate that it is "important but not urgent"...but the longer it is dragged out the longer the lack of clarity exists. |
@e-lo There are already a lot of SHOULDs in the GTFS and GTFS Realtime specs, so I don't see this PR really changing the state of things. It just removes some of those SHOULDs from the best practices list. As everything exists today (prior to merging this PR), if you want a vendor to do everything that the spec itself recommends (i.e., says you should do, but are not required to do), you'd still need language such as the above. |
|
Also, I'd suggest changing the first "should" to "shall" as well:
|
|
Prepared to vote on this, but want to continue hashing out @e-lo's concerns first.
Correct me if I'm wrong, but my understanding is that the Best Practices is not intended to be a one-stop shop for someone figuring out how to implement GTFS (i.e. it doesn't include the spec itself). Having to check more than one place is an inherent reality of the two resources (the spec and Best Practices) existing. Anyone implementing the spec with best practices in mind will still need to refer to both, regardless of whether redundancies exist or not, right? And as @scmcca said, the purpose of this PR is to remove those redundancies so the GTFS community, which is already using both resources in tandem, doesn't have to deal with as much confusion.
I don't see how this PR invalidates this language. You can still refer to files and fields as "included in the base GTFS specification and the GTFS Schedule Best Practices." However, this sentence doesn't include anything explicit about following best practices, just about including files and fields, so maybe it could do with amending anyway?
To me, "consistent with the GTFS Schedule specification" and "follow...recommendations in the specification (noted as SHOULD)" is saying the same thing. If the dream is to have a one-stop shop for all MUSTs and (applicable) SHOULDs, that's something that can't realistically happen "overnight." But this PR is a great step in heading that direction, or at least in cleaning up some repeated information present in official GTFS resources. |
|
+1 from Trillium |
|
The vote ended on 2022-01-24 at 23:59:59 UTC. This PR passes with at least 3 votes in favour and 0 opposed. Thanks to all involved! |
|
We are adding Best Practice rules in our validator, and it looks like the following Best Practice was removed in this PR by mistake, it's not appearing anywhere in the spec. In routes.txt:
Is this correct? If so, I'd like to add it back to the Best Practices. |
7 participants
Here is a review of the Best Practices as they align with the specification. The goal of this PR is to reduce duplicative information and to streamline the documentation.
Each commit has a message explaining the rationale for the change.
Feedback is welcomed.