GBFS documentation versioning and and feed conformance #188

antrim · 2019-11-06T19:12:28Z

Issue #15 contains a discussion thread about versioning GBFS documentation and data. Versioning is needed to enable backwards-compatibility breaking changes.

This PR:

Defines a semantic versioning approach for backwards-compatibility breaking (MAJOR) and backwards-compatible (MINOR) GBFS changes
Includes release practice guidelines, including a long-term support (LTS) version and maximum number of MAJOR releases per year. New versions would be subject to community vote, so these are guidelines, not hard rules.
Defines a backwards-compatible lookup mechanism to disseminate GBFS data feeds encoded in various versions of the specification.
Does not yet include the versionCode concept (integers associated with each named version), but this could be added if requested.

Please comment and propose any changes. @MobilityData proposes to bring this to vote in 1 week or less so that GBFS can begin to incorporate necessary changes that break backwards-compatibility.

First draft proposal

barbeau · 2019-11-06T21:42:27Z

README.md

+
+### Version Release Cycles
+* There is no strict limitation on the frequency of MAJOR releases, but the GBFS community aims to limit the MAJOR releases to 2 or less every 12 months. To limit releases, breaking changes can be batched together.
+* MINOR changes may be applied at any time. There is no guideline to limit the number of MINOR changes.


Are minor changes batched too, or does every change that qualifies as a minor change bump the MINOR version?

I was intentionally silent so that MINOR changes could be batched or not batched, depending on their timeline. My assumption is that if changes occur soon after each other, we might as well batch. But, with backwards-compatibility issues absent, it doesn't make sense to hold back changes too long for a batched version bump. I'll explicitly state this.

I would state this explicitly just so there isn't any confusion.

README.md

gbfs.md

README.md

barbeau · 2019-11-06T22:13:45Z

gbfs.md

        }
      ]
    },
    "fr" : {
      "feeds": [
        {
          "name": "system_information",
-          "url": "https://www.example.com/gbfs/fr/system_information"
+          "url": "https://www.example.com/gbfs/1.0/fr/system_information"


Are we going to remain silent on how versioning should be handled in the URL path?

What do you think? Should we offer a recommendation? As this is written, it's up to the discretion of the feed producers. The examples offer suggestions.

Perhaps we should state that a URL must never change its major version. For example, if a feed doesn't want to include a version in the path, that's fine, but it must not change from v1 to v2 ever.

This actually brings up another question - can a feed change from 1.0 to 1.1? Technically this should not break anything, and it would mean that publishers could have, say, https://www.example.com/gbfs/1/fr/system_information for their feed that conformed to the 1.X spec. Would this be confusing for consumers?

One challenge for dictating versions in URL paths is that it could conflict with existing versioning schemes or numbers used by producers in URL paths. For example, HOPR currently uses integers in the URL path to identify systems - https://gbfs.hopr.city/api/gbfs/6 vs https://gbfs.hopr.city/api/gbfs/8.

So there could be significant backwards compatibility concerns.

If we require the auto-discovery file (see proposal at #189), I'm inclined to let producers manage their own URL paths.

@jcn I just pushed a change that responds to what you pointed out. Please let me know what you think…

gbfs.md

barbeau · 2019-11-06T22:20:57Z

Thanks @antrim! Looks pretty good, I suggested some changes.

heidiguenin

Reviewing after @barbeau means lots of thumbs-up responses from me. Looking good!

README.md

@barbeau

In response to review by @barbeau

antrim

Thanks for your review, @barbeau and @heidiguenin. I've modified the proposal according to most of the suggestions. There is one outstanding question around URL paths and versions.

Proposed next steps

Let's keep this open until Tuesday (UTC) of next week for review and comment.
And then call a vote on Wednesday (UTC). Assuming there is support for this proposal, I propose that we also call a vote on changes that break backwards-compatibility at the same time, preparing to implement the versioning process.

jcn · 2019-11-07T18:14:37Z

A question about the transition from our unversioned to versioned world: should we just state that all unversioned feeds should be considered 1.0? The current spec is considered an implicit 1.0 anyway, so this would help in terms of moving forward, and for consumers of feeds that have not upgraded yet.

jcn · 2019-11-07T18:15:56Z

README.md

@@ -40,6 +40,26 @@ The general outline for changing the spec has 4 steps:
 3.	Find at least one GBFS producer to implement and test the proposed change.
 4.	Submit a final request-for-comments on the proposed change to the issue discussion. If no outstanding issues are identified after one week’s time, and there is general agreement that the proposed change is worthwhile and follows the GBFS guiding principles outlined below, the proposal will be officially adopted.

+## Specification Versioning
+To enable the evolution of GBFS, including changes that would otherwise break backwards-compatibility with consuming applications, GBFS documentation is versioned. A git tag in the form of `X.Y` establishes semantic versions. Multiple changes (commits) may be batched into a single new release.


I think that git tags technically have to start with a letter, so the tag will be vX.Y where the version name itself will be X.Y

jcn · 2019-11-07T18:17:30Z

gbfs.md

+_GBFS producers_ should provide endpoints that conform to both the current specification long term support (LTS) branch as well as the latest release branch within at least 3 months of a new spec `MAJOR` or `MINOR` version release. See [specification versioning](README.md#specification-versioning)
+
+_GBFS consumers_ should, at a minumum, support the current LTS branch. It highly recommended that GBFS consumers support later releases.
+


Is this "should" or "must?" If a producer does not provide LTS and the latest feed, are there any repercussions?

This is framed as a "Best Practice" to work within the bounds of the authority of specification authors. This is a recommendation, not a requirement. Making any sort of requirement with repercussions is the domain of cities and other governments and/or bikeshare contract holders.

A clarifying question: what does "It highly recommended that GBFS consumers support later releases." mean?

jcn · 2019-11-07T18:22:19Z

gbfs.md

 ## Files
 This specification defines the following files along with their associated content:

 File Name                   | Required                |       Defines
 --------------------------- | ----------------------- | ----------
 gbfs.json                   | Optional                | Auto-discovery file that links to all of the other files published by the system. This file is optional, but highly recommended.
+gbfs_versions.json          | Optional                | Lists all feed endpoints published according to versions of the GBFS documentation.


I'm a little confused about where this sits. Does this file get published for every version? i.e. does this file appear in 1.0, 1.1 and 1.2 locations? Regardless, I propose we make it required in order to be able to find all of the relevant feeds.

This file would sit in all the versions.

Proposal: Let's keep this optional for its incorporation into a "1.0" version. Technically, the change is backwards-compatible if we make the file optional.

We could make this required in a future backwards compatibility breaking MAJOR change.

We could make this required in a future backwards compatibility breaking MAJOR change.

Let's update this field to indicate that it will probably become required in a future version so producers are encouraged to start publishing now.

jcn · 2019-11-07T18:26:23Z

gbfs.md

 Example:
 ```json
 {
  "last_updated": 1434054678,
  "ttl": 3600,
+  "version":"1.0",


For consistency with the rest of the documentation, wherever new JSON fields were added, can we add a space after the :?

Good catch. Changed.

jcn · 2019-11-07T18:27:32Z

gbfs.md

+  "ttl": 0,
+  "version":"1.0",
+  "data": {
+    [


This should be

"versions": [

(you're missing the key name)

Good catch. Fixed.

@jcn

"version": "2.1" -> "version": "1.0" as per @jcn suggestion Co-Authored-By: Jesse Chan-Norris <jcn@users.noreply.github.com>

Change example data for gbfs.json to be consistent with a v1.0 example

antrim · 2019-11-21T00:41:28Z

Voting has closed. Both Lime and Transit voted for the change. No organizations voted against.

Current GBFS governing rules say that at least one producer and consumer have to implement the change before it is adopted, I propose that we merge to the master branch (if there are no objections) for these reasons:

The change includes new governance rules.
An agreed upon versioning scheme is a prerequisite for some of the proposed changes that would break backwards-compatibility. Deciding on a versioning scheme now will allow GBFS stakeholders to better plan.
This change change itself is backwards compatible. Consuming software would not need to be changed until a new version is released.

Does anyone have objections to merging into the master branch?

jcn · 2019-11-21T01:05:51Z

I am in favor of this change and in merging it at the end of the voting period but for the sake of process we should wait for the actual end as per your original call for a vote.

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

antrim · 2019-11-21T01:21:42Z

Oops. Sorry about that confusion with the dates. Voting is of course open through Friday.

yocontra · 2019-11-21T01:29:33Z

+1 for Stae

tmontes · 2019-11-21T09:17:02Z

May I suggest that if this PR is merged, as it seems it will, then the repository is tagged as soon as possible: we should have, I suppose, at least a version 1.0 tag that pinpoints which of the more than 20 commits claiming to be version 1.0 in their version histories is actually version 1.0. :-)

Thanks!

tmontes · 2019-11-21T09:20:04Z

PS: For what it's worth, as an independent consultant working on an MDS/GBFS related project, I'm in favour of the proposed changes.

evansiroky · 2019-11-22T00:53:58Z

+1 from IBI Group.

mplsmitch · 2019-11-22T18:37:52Z

+1

sven4all · 2019-11-22T18:44:52Z

+1

antrim · 2019-11-25T21:26:12Z

The change passes! We had 6 votes in favor from consumers or operators and 0 votes against:

Consumers (4): Transit, IBI Group, Openbike, Stae
Operators / producers (2): Lime, Motivate
Unaffiliated (2) - not counted

Next steps:

I'll merge the PR.
We'll begin to implement the versioning scheme by tagging releases. There are a number of PRs open to voting or soon to be, so this is timely!

related to PR #188

fixes the merge of PR #188 addes back section "Files"

heidiguenin · 2020-02-27T22:03:21Z

We'd love to make this an official part of the spec, but first we need to see this change being implemented. Could you comment here if your organization has implemented this?

@johnpena @gcamp @contra @evansiroky @sven4all ?

antrim added 2 commits November 6, 2019 10:35

Spec versioning proposal

29db809

First draft proposal

Corrections to initial commit

ea50d81

antrim added the proposal:breaking label Nov 6, 2019

antrim requested review from barbeau and heidiguenin November 6, 2019 19:12

antrim self-assigned this Nov 6, 2019

antrim mentioned this pull request Nov 6, 2019

Do we need to include GBFS version? #15

Closed