Restructure ODS to "Supplement" Framework

jeffkessler-keolis commented 6 months ago

Proposed documentation for implementation per #55 and discussion on prior working group calls.

Establishes the standard structure for _supplement files and enumerates those provisioned for use with standardized fields.
Updates GTFS reference links to the GTFS repo itself (vs the deprecated Google Transit webpage).
Updates the reference language in this file to TODS (for Transit Operational Data Standard per 2/27/24 call), although other files remain to be updated.
Leaves the runs_pieces.txt and run_events.txt files unmodified in anticipation of a pull request to implement the changes of #60.

An open question remains as to the preferred handling of the TODS_trip_type and TODS_location_type fields, both in their nomenclature and their implementation as a text string (vs enum). I have proposed the two above based on handling in the analogous GTFS files and prior working group discussion about the value of text strings vs enums for varying types needing to be defined by individual operators, although these could certainly be changed per future discussions.

github-actions[bot] commented 6 months ago

Preview url: https://operational-data-standard-61--cal-itp-previews.netlify.app

github-actions[bot] commented 6 months ago

Preview url: https://operational-data-standard-61--cal-itp-previews.netlify.app

jeffkessler-keolis commented 3 months ago

Just bumping this thread since it seems the v2 specification proposal has been stable with no further commentary over the past few months.

@safrazier17 @Cristhian-HA @jfabi Do you know what'd be the next step in progressing the formal adoption of this and @skyqrose's #60? Can we proceed with calling for a vote?

(In terms of the sequencing of things, I think we discussed on the last call to vote on the combined adoption, then merging this in first, followed by Sky's change which includes some references to fields/data herein.)

Thanks!

safrazier17 commented 3 months ago

That’s the next step. I’ll call a vote next week and we can get moving on this PR

On Thu, May 30, 2024 at 6:48 AM Jeff Kessler @.***> wrote:

Just bumping this thread since it seems the v2 specification proposal has been stable with no further commentary over the past few months.

@safrazier17 https://github.com/safrazier17 @Cristhian-HA https://github.com/Cristhian-HA @jfabi https://github.com/jfabi Do you know what'd be the next step in progressing the formal adoption of this and @skyqrose https://github.com/skyqrose's #60 https://github.com/cal-itp/operational-data-standard/issues/60? Can we proceed with calling for a vote?

(In terms of the sequencing of things, I think we discussed on the last call to vote on the combined adoption, then merging this in first, followed by Sky's change which includes some references to fields/data herein.)

Thanks!

— Reply to this email directly, view it on GitHub https://github.com/cal-itp/operational-data-standard/pull/61#issuecomment-2139599634, or unsubscribe https://github.com/notifications/unsubscribe-auth/ALKK7YCZBBTB5MY4WHAEI5TZE4U4DAVCNFSM6AAAAABD6GNE5CVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCMZZGU4TSNRTGQ . You are receiving this because you were mentioned.Message ID: @.***>

safrazier17 commented 3 months ago

VOTING PERIOD OPEN

Voting is open on this PR through 11:59:59 UTC on June 19, 2024. This PR is the first of 2 comprising the TODS 2.0 target release. If adopted, this PR will be versioned as TODS 2.0-alpha.1.

WHO IS ELIGIBLE TO VOTE

Any individual may vote as an ODS Contributor; in voting, Contributors are acknowledging and agreeing to the ODS Contributor Agreement and ODS Code of Conduct.

Issue Working Group members @safrazier17 @jeffkessler-keolis @jfabi @skyqrose are not eligible to vote on this proposal.

HOW TO VOTE

A vote of support for this PR, comment "+1 [Individual or Organization Name]"
To support the proposal with a minor correction, add one comment to the PR including both the correction and "+1 [Individual or Organization Name]"
To vote for a substantial revision to the proposal, comment "-1 [Individual or Organization Name]" along with a brief description of what you believe needs to be substantially revised before the proposal can be adopted. NOTE: TODS governance requires that voters requesting substantial revision commit to working with the Issue Working Group to develop their recommended revision.

OUTCOMES

At the end of the voting period, if the proposal has received at least THREE (3) +1 votes from stakeholders outside of the Issue Working Group and votes of "Support with Minor Correction" or "Substantial Revision," the proposal is immediately adopted.
If the proposal receives one or more votes of "Support with Minor Correction," the Issue Working Group may decide whether to incorporate the recommended changes or to appeal to the Board for consideration of the necessity of the recommended changes.
- If the issue working group or the Board determine that the minor changes should be incorporated into the proposal, the proposal shall be updated and the TODS community shall be notified of the updates. After a period of FOUR (4) business days, the proposal shall be adopted immediately unless valid objections to the minor changes are received. No new voting period is automatically initiated.
If the proposal receives one or more votes of substantial changes, the author(s) of the recommended changes must commit to working with the issue working group to develop an alternative proposal that meets the need raised by the reviewer. The issue working group may appeal to the Board if they believe a recommended substantial change is without merit.
- If a proposal is substantially changed, then a new voting period must be opened before the amended proposal can be adopted.
If the proposal does not meet the minimum threshold for votes outside of the issue working group, the working group may appeal to the Board for a decision. The Board may vote to adopt the proposal or to require a new voting period.

wmata-eajensen commented 3 months ago

+1 WMATA

hunterowens commented 2 months ago

+1 Cal-ITP / Caltrans!

jeffkessler-keolis commented 2 months ago

Since there was some feedback requesting a summary of the motivation behind this change, the summary is:

Many large/complex operators, especially rail operators, do not have a clear delineation between revenue/nonrevenue trips.
The current v1 standard is unusable for these operators since there is no current mechanism to update/modify/add information to trips that already exist in GTFS.
The supplement structure provides a clean way to update/modify/add information to the content already published in GTFS.
Since the existing TODS files of deadheads.txt, ops_locations.txt, and deadhead_times.txt are effectively adding non-public information to existing GTFS files (of trips.txt, stops.txt, and stop_times.txt, respectively), their content is moved to the more multipurpose supplement files.

tl;dr The supplement framework allows complex operators (e.g. rail) to model much greater complexity and combine public and non-public information as required using a standardized approach that builds atop existing GTFS.

For more details and examples of the motivation behind this change, see https://github.com/cal-itp/operational-data-standard/issues/55.

safrazier17 commented 2 months ago

VOTING PERIOD CLOSED

The voting period for this proposal closed yesterday, June 19 at 11:59:59 UTC. The proposal received the following votes:

Support (3): @wmata-eajensen (WMATA), @paulswartz (MBTA), @hunterowens (Caltrans) Support with minor correction (0): No votes recorded Substantial Revision (0): No votes recorded

The proposal has met the threshold of support needed and passes.

The Issue Working Group (@jeffkessler-keolis, @skyqrose, @safrazier17, @jfabi) is considering a minor recommended change from @mads14 (Swiftly) that was not tied to a vote. If the issue working group decides to adopt this change, those voters who cast supportive votes will have a period of four (4) days in which to review and withdraw their support based on this change if they so choose. This is not a new vote window and no new votes will affect the outcome of this proposal.

If withdrawals of support cause the proposal to fall beneath the required threshold of support for passage, the Issue Working Group will decide whether to revert to the previously passed version of the proposal, initiate a new voting window for the proposal, or appeal to the Board for a determination.

If support for the proposal remains above the threshold of support needed for passage, the proposal will immediately be adopted at the end of four days as TODS 2.0-alpha.1.

paulswartz commented 2 months ago

I saw @mads14 's proposal and that would not change my vote.

wmata-eajensen commented 2 months ago

Can also confirm the @mads14 proposal will not change my vote (I will continue to support)

safrazier17 commented 2 months ago

FINAL VOTE AND ACTIONS

After further discussion, the Issue Working Group decided not to adopt the proposed change of filenames from _supplement to _TODS_supplement for the following reasons:

The Issue Working Group had doubts about whether there were other divisions beyond the internal-facing/external-facing division that would be appropriate for supplementing GTFS without being part of TODS
The Issue Working Group had concerns about whether there were logical complications introduced by having multiple files supplementing a single GTFS feed, which had not been fully worked through

As previously announced, the proposal passes with 3 votes in support and none in opposition. The vote and this discussion will be recorded on the website, and TODS 2.0-alpha.1 will be added to the revision history for TODS on the website.

In the coming days, we expect to take up the second of two PRs for the final TODS 2.0 release. That PR is #66 for those interested in reviewing it / making comments before voting opens.

cal-itp / operational-data-standard