Versioning and Long Term Support #386
Conversation
Updates README with table of supported versions, replacing complete version history. Changes language related to Long Term Support
Updates "What is GBFS?" to list supported modes.
Update name , leave acronym alone
This reverts commit 704511d.
This reverts commit 7201e34.
This reverts commit 33be600.
This reverts commit feab2e9.
Adds link to version history on wiki
Revises Version Endpoints section, removing references to LTS branch.
|
I hereby call a vote on this proposal. Voting will be open for 10 full calendar days until 11:59PM UTC on December 9, 2021. 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. |
|
Hi, thanks for putting this together. +1 in principle from Google Maps for having more clear versioning and support information. I've left some comments to clarify the changes better. |
| @@ -119,11 +106,19 @@ Announcements for disruptions of service, including disabled stations or tempora | |||
| * REQUIRED files MUST NOT 404. They MUST return a properly formatted JSON file as defined in [Output Format](#output-format). | |||
| * OPTIONAL files MAY 404. A 404 of an OPTIONAL file SHOULD NOT be considered an error. | |||
|
|
|||
| ### Version Endpoints | |||
|
|
|||
| The version of the GBFS specification to which a feed conforms is declared in the `version` field in all files. See [Output Format](#output-format).<br /> | |||
There was a problem hiding this comment.
Should there be a recommendation that all feeds should be on the same version? E.g. not to want to mix v1.1 station_information with v2.2 vehicle_types.
There was a problem hiding this comment.
At the developers' workshop, there was mixed feedback about this. At least one consumer said they don't even check the versions but just go feature by feature. Right now, the spec doesn't have anything specific to say about this, so maybe it's a good question for the industry practices survey and we can update it once we learn more about current practice and preferred practice?
There was a problem hiding this comment.
It makes validation difficult if there's mix of versions. Seems like at least all feeds should be part of the same MAJOR version.
|
|
||
| The version of the GBFS specification to which a feed conforms is declared in the `version` field in all files. See [Output Format](#output-format).<br /> | ||
|
|
||
| GBFS documentation will include a list of current and past supported MAJOR and MINOR versions. Supported versions SHALL NOT span more than two MAJOR versions. Past versions with _Supported_ status MAY be patched to correct bugs or vulnerabilities but new features will not be introduced. Past versions with _Deprecated_ status will not be patched and their use SHOULD be discontinued. Producers SHOULD continue to maintain existing feeds while they have _Supported_ status. |
There was a problem hiding this comment.
Could there be some guidance for announcing that a version is getting deprecated 180 days before, so that consumers have time to move off it before producers can stop supporting it? Also, will there be a community vote on deprecating a version or this is implicit by approving a new major version?
There was a problem hiding this comment.
We could write in that deprecation would happen 180 days after a MAJOR release candidate becomes official. Deprecation would not be subject to a vote, it would happen automatically.
heidiguenin
added
v2.3-RC2
and removed
v3.0-RC
|
+1 from Transit |
|
+1 from Google Maps |
|
Entur supports this proposal |
|
+1 from nextbike |
|
Voting on this PR closes in 2 calendar days. 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. |
|
+1 from Spin |
|
+1 from TIER |
|
This vote has now closed, and it passes! Votes in favor: There were no votes against. We'll update the documentation as discussed, and then we will tag and merge this into v2.3-RC2 in the coming weeks. |
heidiguenin
added
Vote Passed
and removed
proposal:nonbreaking
Vote Closing Soon
labels
What problem does your proposal solve? Please begin with the relevant issue number. If there is no existing issue, please also describe alternative solutions you have considered.
The concept of Long Term Support (or LTS) was introduced along with versioning in v1.1. A branch was to be designated as the Long Term Support branch via the voting process, however this was never implemented. The idea of LTS was to give consumers time to adapt their software to a new version before the feed for the previous version goes away. Additionally, producers have the added challenge of having to support multiple version because of differing requirements placed on them by municipalities across different markets. Some of these may be far behind the current specification and could contain bugs or vulnerabilities and as such should no longer be used.
Discussion is in Issue #358 and in the Dev workshop notes here.
What is the proposal?
In discussion at the GBFS developer's workshop on October 19 it was determined that clearer guidance was needed around which versions should continue to be used and which should be deprecated.
This proposal removes language in the README and gbfs.json around Long Term Support and categorizes versions as follows:
Current Version - This is the most recent release of the specification
In Development - This is the next MAJOR version draft
Release Candidate - This Release Candidate will become the Current Version when it has been fully implemented in public feeds. It may be either a MAJOR or MINOR version.
Supported - These are past versions that MAY be patched to correct bugs or vulnerabilities but new features will not be introduced.
Deprecated - These are past versions that will not be patched and their use SHOULD be discontinued.
All versions are categorized as described above in a table on the README. The full version history has been relocated to a page on the Wiki.
It's recommended that GBFS producers provide endpoints that conform to the current MAJOR version release within 180 days of a new MAJOR version release. Producers SHOULD continue to maintain existing feeds while they have Supported status. Supported versions will not span more than two MAJOR releases so providers would never have to support more than two MAJOR versions.
Is this a breaking change?
Which files are affected by this change?