Governance pilot proposal & upcoming changes

[antrim]

NABSA has selected MobilityData IO (@MobilityData) to support them in their work to update and enhance GBFS, as mentioned in issue #137. MobilityData works to improve the coverage, completeness, and quality of mobility data standards around the world, including the General Transit Feed Specification (GTFS). GBFS has been modeled off of GTFS in many ways, and we'll continue to borrow relevant lessons from GTFS - including during this governance pilot.

Currently, GBFS' change process is not as detailed as may be necessary to effectively clarify and enhance the spec. In the coming weeks we'll be working to clarify and enhance GBFS. We propose piloting the GTFS change framework within the GBFS repo as we do this work. (Some parts of the process, such as the CLA and the mailing list, are not relevant for GBFS and will not be used.)

In some cases, piloting the GTFS change framework may mean working with the authors of pull requests or issues to combine or split posts up. For example, pull request #92 may be a good candidate for moving some parts of the conversation to their own issue or pull request.

Please respond if you have a specific objection we can address or if you support this pilot governance proposal.

[antrim]

Update on the governance pilot:

We have been following the voting process of the GTFS change framework, which requires at least seven days of voting and unanimous yes votes, with at least three votes total from including at least one vote each from a producer and consumer.

In order to ensure practicality, the GTFS change framework also requires that any accepted specification change must first be implemented in at least one dataset and in at least one consuming application. Over the past 5 months, @MobilityData has not strictly observed this other requirement in our facilitation of the GBFS change process because we believed it would greatly slow down the process of catching GBFS up with shared mobility industry practice. We have tried to ensure practicality by calling votes on "minimum viable proposals" and asking stakeholders to commit to implement the proposal on an unspecified timeline.

We propose to codify this process thus:

• Any change proposal should be open on GitHub for at least 7 days of discussion before voting.
• Each part of the proposal must have at least one organization committed to its implementation: either at least one organization committed to implementing the entire proposal or separate organizations committed to partial implementations.
• For changes to the specification at least 3 votes in favor are required for a proposal to pass.
• Voting is announced by a message that conforms to this template:

I hereby call a vote on this proposal. Voting will be open for 7 full days, until 11:59PM UTC on X.

Please vote for or against the proposal, and include the organization for which you are voting in your comment.

Please note if you can commit to implementing the proposal.

After GBFS is more up-to-date with industry practice and we can change more incrementally, we suggest considering a process that requires implementation, like GTFS. One such DRAFT process is as follows.

• Accepted changes not yet implemented in software will be marked as "Beta" in the master branch of the GBFS.
• Once implemented in at least one GBFS feed and one piece of consuming software, then changes can become part of a marked release, according to the versioning framework.

At the time when we end the governance pilot and propose an official governance process, we will poll all stakeholders for approval of this process.

Please respond if you have objections, concerns, or suggestions regarding the above approach. (Or just a thumbs up if you support it.)

[barbeau]

@antrim This governance approach looks good to me!

One clarifying question - GTFS only mentions producers and consumers in context of implementing new features. https://github.com/google/transit/blob/master/gtfs/CHANGES.md says:

Before calling for a vote, at least one GTFS producer and one GTFS consumer should implement the proposed change.

So, for semantic changes to the GTFS spec, at least 3 votes in favor are required for a proposal to pass, but it's not a requirement to have at least one vote each from a producer and consumer (e.g., all 3 votes could be from consumers).

So if we're following the GTFS process, for semantic changes to the GBFS spec like #189 the vote would pass as long as we have at least 3 votes, regardless if they are producers or consumers.

Could you please clarify this?

[antrim]

Thanks for noticing this and clarifying GTFS practice. I modified the update #163 (comment). We'd require 3 votes for semantic changes. At least one producer and one consumer would be required to add changes to a release. Do you think that's a sensible adaptation?

[barbeau]

At least one producer and one consumer would be required to add changes to a release. Do you think that's a sensible adaptation?

Do you mean to add the semantic changes to a release? I'm not sure I understand the process of how that would work in practice. Would we re-vote on semantic changes prior to tagging a release if they didn't initially pass with a least one producer and consumer?

I think it would be hard to track semantic changes as "beta" in the master branch until the release. For new fields, it's relatively easy - you just add a (beta) suffix. But semantic changes are often re-wording of sentences, or changing fields from optional to required ( #189 for example). I'm not sure there is a good way to label these changes as temporary in the master branch prior to a secondary process of screening them for a release.

Given that the GTFS process for semantic changes has seemed to work ok not requiring at least one producer and one consumer vote, I'd be inclined to keep it the same for GBFS.

[antrim]

Thanks for catching the complications as we try out governance approaches.

I modified #163 (comment) so that the 3 votes requirement applies for all changes (not just semantic).

I see what you're saying about changing definitions of existing fields within this process. Simple process: Should we just include the beta definition, marked as such, in existing to the current?

[barbeau]

Should we just include the beta definition, marked as such, in existing to the current?

I think having two (or more, if there are multiple changes) definitions for a field in the master branch document will be too confusing.

The master branch document is effectively the draft for the next release - maybe we should mark it as such? We always have the Git tags which mark canonical release versions, so if we want to look back to see what the v1.0 definition of a field was we can consult that.

Eventually we should have a site for GBFS like https://gtfs.org/ which would show canonical releases, as well as the next draft release, in an easier-to-digest format.

[josee-sabourin]

Hi all! We have opened PR 253 to discuss updating the governance, would love to have everyone's feedback.