search

MobilityData / gbfs

Documentation for the General Bikeshare Feed Specification, a standardized data feed for shared mobility system availability. Maintained by MobilityData
https://gbfs.org
Other
784 stars 286 forks source link

Governance pilot proposal & upcoming changes #163

Closed antrim closed 4 years ago

antrim commented 5 years ago

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 commented 4 years ago

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:

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.

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 commented 4 years ago

@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 https://github.com/NABSA/gbfs/pull/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 commented 4 years ago

Thanks for noticing this and clarifying GTFS practice. I modified the update https://github.com/NABSA/gbfs/issues/163#issuecomment-559218562. 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 commented 4 years ago

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 commented 4 years ago

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

I modified https://github.com/NABSA/gbfs/issues/163#issuecomment-559218562 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 commented 4 years ago

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 commented 4 years ago

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