Modifications to the GTFS Governance: Phasing Plan

[eliasmbd]

🗒️ Context

After conducting numerous interviews and workshops throughout 2023, MobilityData is suggesting several refinements to address common problems in both the formal amendment process and the informal processes related to GTFS governance.

In this issue, you will find a summary of the most common problems as highlighted by the community.

🤔 Problems

High barrier to entry

• Scattered communication leads to confusion regarding where to access key information.
• Confusion on where the source of truth for documentation lies.
• Lack of overview on what is actively being discussed.
• The governance process is designed for major changes, creating an intimidating barrier for individuals seeking to propose minor improvements.

Insufficient engagement in the proposals in the early stages of development.

• Vague process before the Pull Request stage.
• The level of consensus is frequently unclear until a Pull Request is initiated or a vote is called.
• Reviews are vague, it’s hard to know if a proposal has been thoroughly reviewed before testing and adoption.

First adopters are frequently impacted by last-minute changes to their implementation, leading to an increase in committed resources.

• First Adopters need to implement changes before opening a vote. Certain problems identified too late demand multiple rounds of testing and require supporting various versions of a proposal.

🔮 Phasing Plan

Based on these issues, MobilityData has worked on a phasing plan, which will be updated to represent the current status.

Phase	What’s included	Status
1 - Effective communication and GitHub management	Publication of a monthly “GTFS Digest” that gives an overview of the active conversations in the community and latest additions. Using GitHub issue templates and labels to guide contributors and give a better overview of the status of each issue. https://github.com/google/transit/pull/417 https://github.com/google/transit/issues/419 **[Modified Labels Categorization](https://github.com/google/transit/labels)**	✅ Done
2 - Enhancing voting and reviews	Adding an earlier vote to increase the visibility and potential issues of a proposal early-on. The veto would be moved to this earlier vote to incentivise contributors to review the proposal early and share any major concerns before early adopters implement the changes proposed The final vote would follow a majority vote with a 80% threshold Incorporating review guidelines to simplify the process of providing feedback on proposals. https://github.com/google/transit/issues/436	🚧 WIP
3 - Fast-track process for smaller changes	Adding a lightweight process for smaller changes Other editorial changes on the spec amendment process Including other ways of contributing than via a Pull Request Clarifying the roles and major steps Add a visualization

🔎 Future Considerations

While the phasing plan should address most of the problems highlighted by the GTFS community, some solutions worth exploring remain.

• Merging GTFS Schedule and GTFS Real-time governances
• GTFS Community Platform
• Formalize Working Group
• Adding GTFS Project Roadmap
• Flexibility in 1 Consumer and 1 Producers testing requirements and depreciation of “small” unused fields
• YouTube videos for GTFS changes and other applications

⏩ What’s next?

1. We welcome the GTFS community to comment in the section below and share their thoughts.
2. Questions for the community
   1. Do you think the proposed solutions best help alleviate the problems identified?
   2. Out of the 3 proposed phases, would you split any of them up to include more details?

[e-lo]

💟 I love this in general. ☑️ Thank you for digesting all of the concerns you heard into a plan of action!

Requests:

1. I'd love some more clarity on the two-stage voting process – I don't really understand it as currently described.
2. I'd love a process split by "normative changes" and non-normative as well as large- (e.g. faresv2) vs small (e.g. adding another enum). Non-normative changes are important for making sure the spec is implemented as intended and is supported by good examples and documentation.
3. In addition to the next steps that you've highlighted, "what will it take" to implement these changes and how can we help?

[mmorang]

Thank you. Excellent job summarizing the problems and pain points!! I also like your proposed solutions.

The one thing I would add is that, in addition to the monthly summary of ongoing discussions, there needs to be a low-traffic announcement list in which official changes to the spec are described clearly and concisely as soon as they are officially adopted. I think some people don't necessarily want or need to be involved in the proposals and just need to be informed of changes as soon as they occur.

[gcamp]

👍 this is a step in the right direction. Generally agree with the steps laid out, but curious about the specifics especially of #3.

I would also add in future considerations :

• The "must be implemented by one producer and one consumer" rule is a good rule in spirits, but I think should be more flexible, especially for individual fields when adding a new normative change.

[skinkie]

@gcamp I think for merging the change the 1+1 idea works well. Hence it is implemented and tested. But I also would consider adding an automatic deprecation if nobody would actually picks up the change after those initial parties. 1+1 is still a private extension.

[AdrianaCeric]

Great to see MobilityData actively addressing the challenges in GTFS governance! Reiterating discussions at the European workshop, in addition to the proposed phasing plan, it might be beneficial to consider incorporating representatives from various user groups or constituencies, such as student ambassadors, into the voting and review processes to provide unique perspectives. I believe one of the primary objectives of addressing the "High barrier to entry" concern is to narrow the divide between new contributors (including individual/independent transit developers, youth, students and non-tech transit enthusiasts) and the established community, where private companies tend to dominate the voting processes and discussions in the working groups.

For example, in Phase 1, when considering the publication of the "GTFS Digest," the choice of platform is crucial. If it is only posted on the Slack, it might inadvertently become an echo chamber for the same group of "power-maintainers" of the spec. Options include making the Slack more easily joinable or exploring alternative channels, such as YouTube videos or increased social media/blog presence, to promote the Digest and broaden its reach beyond the existing community.

[westontrillium]

Generally very excited about what's in this plan!

• Adding an earlier vote to increase the visibility and potential issues of a proposal early-on.
  • The veto would be moved to this earlier vote to incentivise contributors to review the proposal early and share any major concerns before early adopters implement the changes proposed
  • The final vote would follow a majority vote with a 80% threshold

I agree with @e-lo; I'd also like more clarity on the above, as well as how it was determined that, for instance, the veto vote is first and the final vote is a majority vote (at an 80% threshold) and not the other way around. How were these specifics determined? Not saying these choices are worse or better than some alternative, just want to understand the reasoning behind them. 🙂

Also, would it be a good idea to have a trial period for this new voting process so we can actually see it in practice, identify any issues, etc., before having to fully commit? We would, of course, have to agree that any votes conducted under the new rules are valid beyond the trial period, but it could be a way of mitigating the greater risk of being stuck with a process we didn't realize was unfeasible at the time of adoption.

[leonardehrenfried]

I'm mostly in favour of this change.

I can however forsee that not everybody can agree what is a "small change". Nevertheless, I think we should try it and resolve issues as they come up.

[westontrillium]

I can however forsee that not everybody can agree what is a "small change". Nevertheless, I think we should try it and resolve issues as they come up.

Yes, it would probably be good to have a specific, measurable threshold if possible. "X number of new fields/files or more constitutes a large change," etc.

[abyrd]

I just created issue #415 to describe something that I think may be a major factor affecting timely review and comprehensive understanding of change proposals.

[eliasmbd]

We would like to thank everyone who took the time to review the proposed phasing plan and we are encouraged by your excitement! 🙏

We are currently working on Phase 1 with some of the features being finalized as we speak.

Clarifications on Voting in Phase 2

@e-lo @westontrillium

Vote before testing with Veto

• By placing the veto before the testing phase, we aim to increase reviews and discussions earlier in the process, leading to a more predictable testing phase. Verifying consensus at this stage allows for efficient resource management for both first consumers and producers. This approach reduces uncertainty and instills confidence in first producers and consumers during testing.

Vote for adoption with 80% threshold

• We are hoping to increase the incentive to voting and reduce the effect of a veto at this stage.

Additional details will be shared in a proposal to be published in early Q1 2024, including specifics on how this will impact the amendment process. We can anticipate the need for at least one Working Meeting to discuss and evaluate these voting changes.

Clarifications on Phase 3 - Fast-track process for smaller changes

@gcamp @e-lo @leonardehrenfried

While drafting this plan, we identified that Phase 3 is dependent on phase 2 so, we can expect a proposal for this after the adoption of Phase 2. The idea is to distinguish between "large" and "small" changes. Certains changes may not need to be tested by a producer and a consumer, or even need a vote.

How would you differentiate a normative vs non-normative change, a smaller or a bigger change? How would you name them?

The GTFS Digest

@mmorang @AdrianaCeric

We plan to release the Digest in the upcoming week, offering more comprehensive details upon release. It will be available on a publicly accessible Google Group with a subscription option. Expect a monthly release around the mid-month mark, featuring updates on GTFS development and information on new specification adoptions. The appropriate channels will be used for promotion (i.e. LinkedIn, Slack, GitHub, ... )

We also have other locations for GTFS updates that are currently available:

• GTFS.org - Changes : Recent Changes to the spec with a short description
• GTFS.org - Revision History : A history of recently adopted changes
• GTFS-Changes Google Group: An announcement board for changes as decribed in the current amendment process.

We understand that these may not be optimized at the moment but we hope to improve their visibility and quality soon.

As for videos on “YouTube”, we really like the idea but we see this as something we might want to do once the governance phasing plan is accomplished. At the moment, we do not have the capacity to do both but we will put in the future considerations.

Flexibility in 1 Consumer and 1 Producers testing requirements and depreciation of “small” unused fields

@gcamp @skinkie

This is a very interesting proposal that we can either bring up during phase 3 discussions or place it in the future considerations sections.

Trial period for voting changes

@westontrillium

This is interesting. How do you see this work in practice?

[e-lo]

Trial period for voting changes @westontrillium

This is interesting. How do you see this work in practice?

This is sort of what happens in realtime now with experimental fields...which technically allow removal w/out undoing backwards compatibility but this hasn't been done in practice that I am aware of.

Straw person for implementation:

1. Approval of change doesn't require implementation, but a soft commitment to implement.
2. Trial period starts after approval and ends after implemented by a producer and consumer at which point this flag is removed.
3. Trial period can expire after 1 year after which it will either be removed or renewed by another vote.
4. ❓ Could changes be made during the trial period if implementers find an issue?

[e-lo]

Vote before testing with Veto By placing the veto before the testing phase, we aim to increase reviews and discussions earlier in the process, leading to a more predictable testing phase. Verifying consensus at this stage allows for efficient resource management for both first consumers and producers. This approach reduces uncertainty and instills confidence in first producers and consumers during testing.

I'm still not clear about what this process looks like. Are you saying that the initial vote would require unanimity? That seems like a tall order when you don't know necessarily what you are approving.

[westontrillium]

@eliasmbd @e-lo Sorry if I was unclear. What I mean is a trial period of the voting process itself, i.e., there is an agreement to implement the voting process as a provisional change and then have a sort of referendum vote at the end of that period deciding if we lock in the new process or revert to the original. The assumption I'm going on is that there is inherent risk in immediately fully committing to any untested change in process. Maybe that risk is minimal, maybe any change is better than the status quo, but we won't really know how a new voting process will work out until we implement it and that gives me some pause.

For what it's worth, my first impression of the proposed voting process change is definitely positive, I just want to make sure we approach such a change intelligently.

Edit: I realize I forgot to actually provide an example. One way it could work in practice is:

1. Initial vote

   • New voting process discussed, proposal finalized, a vote takes place to adopt it
   • The initial vote has the provision that the new process is effective from X date to, say, two years from X date.

2. Trial period

   • MobilityData tracks pain points, successes, failures, gaps, etc., and encourage community members to commit to doing the same. All votes during this period are considered valid beyond the trial period, regardless of outcome of the referendum vote.

3. Referendum vote

   • Use the collectively gathered data, anecdotal or otherwise, to help determine if this change was actually an improvement.
   • MobilityData calls a vote on whether to officially adopt this new process or revert back to the original and open the discussion for alternative improvements to the process.

[e-lo]

@eliasmbd @e-lo Sorry if I was unclear. What I mean is a trial period of the voting process itself

OoooooOOOOooo. Gotcha :-) (finally)

[isabelle-dr]

Adding a clarification after @e-lo 's comment:

That seems like a tall order when you don't know necessarily what you are approving.

This first vote would be called in the Pull Request, with the exact spec changes & all additional documentation going with a proposed change. Looking at examples of PRs, this initial vote could happen:

• at this stage for #355.
• at this stage for #286.

Note that we are also working on integrating review guidelines in the same phase to make it easier for contributors to review and further increase chances of identifying issues that might remain.

Upon the outcome of this vote, the proposal advances to the testing phase, during which we require the presence of at least 1 producer and 1 consumer to incorporate the latest changes, with more confidence that major risks have been identified. (This could be the opportune time to also update the canonical validator!) We could define what changes are accepted as a result of the testing phase without going back to the first vote (e. g. needs a small clarification or a change to a field name).

Although this might partially address the Insufficient engagement in the proposals in the early stages of development problem, this is mainly intended to address the First adopters are frequently impacted by last-minute changes to their implementation, leading to an increase in committed resources problem. We anticipate that other solutions will primarily address the early engagement before the PR stage, such as the GTFS Digest publication, a better use of GitHub features on this repo, a change to the spec amendment process to better represent all the ways one can contribute (example).

Now you might be wondering: why do we even need a second vote then? This is a good question 🙂.

In GBFS, changes are voted in several PRs to be part of a Release Candidate. The Release Candidate becomes an official Release when the changes are implemented in production (a Release Candidate becoming official is as as simple as this). Small editorial changes can happen during the Release Candidate phase based on community feedback.

In GTFS Realtime, a first vote occurs to add a field as experimental. This first vote needs unanimous consensus yes with at least 3 votes (example). Then, a second PR can be opened to change the field status to official. This second vote needs 80% yes (example). An experimental field is in theory deprecated if not officially adopted within 2 years (which joins @skinkie 's comment), although not done in practice as @e-lo pointed out.

These have the advantage of having longer testing periods. That being said, keeping the two "steps" (1- we think this is a good idea and 2- it works in practice) inside one single PR has the advantage of making the changes resulting from testing immediately and retaining a certain simplicity. Additionally, longer test periods don't necessarily mean stronger testing: we also could imagine requiring more than 1 producer and 1 consumer to implement changes. The second vote could act as a final check on compliance with the amendment process.

Thoughts?

[gcamp]

Agree with what you said @isabelle-dr in the previous message, one small thing is that I would make the first vote before the example given. Before any consumer or producer actually starts working on that. In Fares-v2 that would be even before an issue would be open (probably sometime after the initial feedback on the google doc)

It could mean months or even years between the two votes, but I think that's ok.

[abyrd]

Thanks for your efforts to share the feedback you’ve received, and for your ideas on the specification change process. In principle, the idea of voting early on proposed changes makes sense to me, as does a more uniform process between scheduled and realtime GTFS specifications. However, after reading all the above comments, I still have some questions about what this would look like in practice, and questions about some underlying assumptions.

a) How complete does the early proposal need to be? Can it be only a concept (in an extreme example, a single sentence)? Or at the opposite extreme, does it need to include a full description of all changes to file formats, or a full description of changes to the underlying data model those file formats represent? Are these descriptions required to be complete, clear, or readily approachable by people who will not actually use them but must evaluate their suitability for inclusion in the spec? For example, are there requirements for visualizations or summary tables of some kind?

b) How close does this early description need to be to the final form at the later vote? For example, if the early proposal adds one optional field to a CSV file, can this be followed by a vote on a final proposal that adds a whole new file and requried fields? At what point is this not the same proposal?

c) Is the first vote actually required to precede any prototyping or testing? What if a proposal is made based on an existing prototype or de facto usage?

The idea of the early vote seems to be based on the premise that people or organizations plan changes in advance and seek approval for those ideas or plans before implementing them (even in a preliminary way for testing). My sense is that in practice, people build prototypes almost immediately from loose specifications and move on very quickly to using them, sometimes even in production in local regions, which is only later followed by a move to “get it into the spec”. I'm not saying there's anything inherently bad about this approach, I’m just describing what I see. Building a prototype and confronting it with practical use is a good way to develop and refine one’s ideas and get them into a workable state that can inform a later specification change proposal.

Are these standardization process changes intended to induce changes in existing development practices that (at least in the GTFS world) are generally iterative and fast-moving? If not, is there a possibility of divergence between software development and standardization, where the standardization process feigns an early approval and testing period, while in practice software development has already moved on to production use and will experience exactly the same tension between a locally suffcient implementation and broader community expectations for changes to a global standard?

Put differently, is the difficulty with proposing changes truly one of timing, or just that participants in the process don’t have the time and budget to work on a standardization process, as they’ve often only been hired to make something that works for their own use case or their own customers, and up to project or organization-specific quality expectations?

[abyrd]

@gcamp wrote:

• The "must be implemented by one producer and one consumer" rule is a good rule in spirits, but I think should be more flexible, especially for individual fields when adding a new normative change.

What would be the underlying reason for removing this requirement for one producer and one consumer? What is the advantage of adding things to the specification that have never actually been used to produce or consume data?

I'm not opposing any discussion of changes to the rule. I just genuinely don't know what the intended outcome is here.

[skinkie]

What would be the underlying reason for removing this requirement for one producer and one consumer? What is the advantage of adding things to the specification that have never actually been used to produce or consume data?

From my perspective the one to one relationship will still create private extensions between two parties. I am not at all happy that one actual data exchange would justify extending the schema, without a requirement for any other party to implement it.

[gcamp]

What would be the underlying reason for removing this requirement for one producer and one consumer?

@abyrd I wouldn't remove it but make it more flexible. Concrete examples :

• Text to speech has been added to tts_stop_name but not other fields. Even if there's clearly a benefit on adding tts fields on route name fields and headsigns, because there was only a stop tts_stop_name producer at the time of the vote.
• GTFS-flex : mean_duration_factor, mean_duration_offset, safe_duration_factor, safe_duration_offset fields aren't used by any consumer (mainly because shortcuts were used in the implementation). Everyone agrees that the fields themselves are useful. Should we don't include those fields and have a spec with a clear 'hole' in it?
• A situation I clearly see happening in the future : frequencies.txt are often not supported or badly supported by consumer. If there's a proposal for a new feature that doesn't support frequencies without adding a new field that won't be used. Should that feature not support frequencies at all?
• (edit) This is the prefect example of a change I don't think should require a producer/consumer https://github.com/google/transit/issues/424

The idea of the early vote seems to be based on the premise that people or organizations plan changes in advance and seek approval for those ideas or plans before implementing them (even in a preliminary way for testing).

That's what is happening a lot of time, that's what happened with pathways and with fares-v2. With Trip-Modifications we had an internal version but we asked for comments before Swiftly started implementation.

I agree with small changes it often start internal, but if standardisation is a goal from the start, having a way to reduce risk of late and expensive change just before the final vote is really valuable.

[eliasmbd]

Phase 1 as been marked as done with the completion of labels.

Currently, proposed changes to governance are not reflected in the existing labels. Modification of labels is a possibility as governance undergoes changes.

Moving forward, MobilityData will shift its attention to Phase 2 and draft a proposal. Your input, as outlined in the comments above, will be taken into consideration, and we are committed to keeping you actively involved. More information to come.

[eliasmbd]

Working Group Meeting Announcement

We will be holding our first Working Group Meeting on the subject of Governance on May 2nd @ 11AM EDT

We will build off of last meeting's discussions and focus our discussions on the smaller items. We will try to build concensus on one item at the time.

We will be using Miro for this meeting. We also have a Working Group channel on the MobilityData Slack.

Let us know if you can't make it. We plan on providing asynchronous options like recordings.

To sign up click here

Join the MobilityData Slack to be included in the working group channel.

[eliasmbd]

📯Check out the outcomes of Governance Working Group Meetings📯

[eliasmbd]

Check out the new look of GTFS.org.

We hope this will help guide newcomers and veterans alike to where they need to go in just a few clicks and reduce some barriers for non-technical people as well.