Best practices: add recommended presence

[emmambd]

Problem and Suggested Scope

Referenced from #375 and #376:

MobilityData’s heard a number of pains from the community about the GTFS best practices living in two different places: the spec's SHOULD statements, and the GTFS Best Practices.

• Stakeholders are not always aware of the existence of 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

We’ve been exploring what a good starting “release” or iteration would look like to begin this work. Based on feedback in #375 and some other discussions, it looks like the one key starting point is providing clear guidelines in the specification for when a field or file is recommended for use.

Before creating this PR, we did an initial review of all places in the spec and best practices where they offer advice on when to add a file or field. This spreadsheet also includes the corresponding Canonical Validator rule for each best practice for cross-referencing.

Proposed solution

Adding a Recommended presence in the spec that conforms to RFC conventions. This would make it possible to clearly state that a field or file is not required, but adding it is a best practice that should be considered. Making it immediately obvious that a file or field is recommended in the spec reduces confusion, while preserving backwards compatibility.

This change would not affect validity or the quality evaluation of the dataset according to the Canonical Validator, since the best practices are already translated to warnings in the validator. Any missing recommended field or file would generate a warning in the validator.

If the associated PR is adopted, MobilityData will open a PR on https://github.com/MobilityData/GTFS_Schedule_Best-Practices so that all best practices that have been reconciled + adopted into the spec are removed from the best practices repo.

When is a file/field Recommended instead of Optional?

The Recommended presence is used for any file/field that should be used universally, e.g feed_info.txt or agency_id. This is information producers should provide in all circumstances, but is not required in order to preserve backwards compatibility.

Any file/field that is recommended only under specific circumstances (such as route_short_name when there is a brief service designation) keeps the Optional presence and the words "SHOULD" and/or "recommended" are used in its description.

Alternatives considered

Adding no additional presences and keeping all SHOULDs in the description
The concern with this approach was that it remains confusing for producers for a file/field to be optional but recommended in all cases. Conversation here.

Adding a Conditionally Recommended presence
This was originally drafted, this seemed to overly complicate the spec and create confusion about the difference between Recommended presences and the Optional presence. Conversation here.

[gcamp]

👏 left a couple comments

[Sergiodero]

Hey @gcamp, Sergio from MobilityData here. We've added a new commit that removes the May be provided for frequency-based trips text. We’re proposing to remove this and instead incorporate a use case in the GTFS.org example section to illustrate the use of block_id with frequency based trips, this example could be similar to the one @antrim shared in issue #227.

Currently we’re exploring what could be a good example or use case, but we think that this could be a separate discussion as it would fall on the GTFS.org repo, allowing us to move forward with the discussion in this PR, while simultaneously working on defining this example.

[emmambd]

Since all PR comments have been resolved and there's been engagement and interest in #376 and #376, I'm opening the vote. This PR adds a recommended presence to the spec and best practices for when specific files and fields should be added. These guidelines are taken from GTFS Best Practices.

Please vote with a +1 (for) or -1 (against) in the comments. Voting ends on 2023-07-31 at 23:59:59 UTC.

[gcamp]

+1 Transit

[markstos]

+1 RideAmigos

[westontrillium]

+1 Trillium

[derhuerst]

+1 bbnavi

[doconnoronca]

+1 TransSee

[NomeQ]

+1 Garnet

[evansiroky]

+1 Cal-ITP.

[philip-cline]

+1 Arcadis IBI

[bdferris-v2]

+1 Google

One formatting nit: for the shapes.txt - shape_dist_traveled addition, was the intention that the "Example" be rendered inside the table cell for the shape_dist_traveled field? If so, I think you need to get rid of the line break before the <hr>*Example line because it causes the content to break out of the table cell.

[emmambd]

@bdferris-v2 Thanks for catching that! Corrected.

[emmambd]

The vote passed on 2023-07-31 at 23:59:59 UTC.

9 votes in favour and no votes against.

The votes came from:
Transit (@gcamp)
RideAmigos (@markstos)
Trillium (@westontrillium)
bbnavi (@derhuerst)
TransSee (@doconnoronca)
Garnet (@NomeQ)
Cal-ITP (@evansiroky)
Arcadis IBI (@philip-cline)
Google (@bdferris-v2)

Thanks to everyone who contributed and voted! There will be a PR on the Best Practices repo to remove these from the best practices now that they're duplicated. You can follow the progress on this here.

[emmambd]

👋 Here's an update to go vote to remove these same best practices from the Best Practices repo so we don't have duplicate guidance: MobilityData/GTFS_Schedule_Best-Practices#59.

Voting ends on 2023-08-29 at 23:59:59 UTC.