Versioning and Long Term Support #386
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -4,8 +4,7 @@ Documentation for the General Bikeshare Feed Specification, a standardized data | |
| ## Table of Contents | ||
| * [What is GBFS?](#what-is-gbfs) | ||
| * [Get Involved](#get-involved) | ||
| * [Current Version](#current-version-recommended) | ||
| * [Governance & Overview of the Change Process](#governance--overview-of-the-change-process) | ||
| * [Guiding Principles](#guiding-principles) | ||
| * [Specification Versioning](#specification-versioning) | ||
|
|
@@ -28,59 +27,59 @@ The specification has been designed with the following concepts in mind: | |
| The data in the specification contained in this document is intended for consumption by clients intending to provide real-time (or semi-real-time) transit advice and is designed as such. | ||
| ## Get Involved | ||
| GBFS is an open source project developed under a consensus-based governance model. Contributors come from across the shared mobility industry, public sector, civic technology and elsewhere. Comments or questions can be addressed to the community by [opening an issue](https://github.com/NABSA/gbfs/issues). Proposals for changes or additions to the specification can be made through [pull requests](https://github.com/NABSA/gbfs/pulls). Questions can also be addressed to the community via the [public GBFS Slack channel](https://bit.ly/mobilitydata-slack) or to the shared mobility staff at MobilityData: [[email protected]](mailto:[email protected]) | ||
|
|
||
| ## Current Version *(Recommended)* | ||
| | Version | Type | Release Date | Status | JSON Schema | Release Notes | | ||
| |:---:|:---:|---|---|---| ---| | ||
| | [v2.2](https://github.com/NABSA/gbfs/blob/v2.2/gbfs.md) | MINOR | March 19, 2021 | :white_check_mark: *Current Version* | [v2.2 Schema](https://github.com/MobilityData/gbfs-json-schema/tree/v2.2)| [v2.2 Article](https://mobilitydata.org/cities-gbfs-v2-2-is-here-for-you/) | | ||
|
|
||
| ### Upcoming MAJOR Version | ||
| | Version | Type | Release Target | Status | | ||
| |---|:---:|---|---| | ||
| | [v3.0-Draft](https://github.com/NABSA/gbfs/blob/master/gbfs.md) | MAJOR | Q1, 2022 | :construction: *In Development* | | ||
|
|
||
| ### Release Candidate | ||
| This Release Candidate will become the *Current Version* when it has been fully implemented in public feeds. | ||
|
|
||
| | Version | Type | Release Date | Status | JSON Schema | Release Notes | | ||
| |:---:|:---:|---|---|---|---| | ||
| | [v2.3-RC](https://github.com/NABSA/gbfs/blob/v2.3-RC/gbfs.md) | MINOR | September 8th, 2021 | :white_check_mark: *Release Candidate<br /> (Recommended)* | *coming soon* | [v2.3-RC Article](https://mobilitydata.org/gbfs-v2-3-rc-is-here-to-fix-some-of-your-problems/) | | ||
|
|
||
| ### Past Version Releases | ||
| Past versions with *Supported* status MAY be patched to correct bugs or vulnerabilities but new features will not be introduced.<br /> | ||
| Past versions with *Deprecated* status will not be patched and their use SHOULD be discontinued. | ||
|
|
||
| | Version | Type | Release Date | Status | JSON Schema | Release Notes | | ||
| |:---:|:---:|---|---|---|---| | ||
| | [v2.1](https://github.com/NABSA/gbfs/blob/v2.1/gbfs.md) | MINOR | March 18, 2021 |:white_check_mark: *Supported* | [v2.1 Schema](https://github.com/MobilityData/gbfs-json-schema/tree/v2.1)| [v2.1 Article](https://mobilitydata.org/gbfs-now-fully-supports-dockless-systems-%f0%9f%9b%b4%f0%9f%91%8f/) | ||
| | [v2.0](https://github.com/NABSA/gbfs/blob/v2.0/gbfs.md) | MAJOR | March 16, 2020 | :white_check_mark: *Supported* | [v2.0 Schema](https://github.com/MobilityData/gbfs-json-schema/tree/v2.0) | [v2.0 Article](https://mobilitydata.org/whats-new-in-gbfs-v2-0-%f0%9f%9a%b2%f0%9f%9b%b4/) | | ||
| | [v1.1](https://github.com/NABSA/gbfs/blob/v1.1/gbfs.md) | MINOR | March 16, 2020 |:white_check_mark: *Supported* | [v1.1 Schema](https://github.com/MobilityData/gbfs-json-schema/tree/v1.1) | | | ||
| | [v1.0](https://github.com/NABSA/gbfs/blob/v1.0/gbfs.md) | MAJOR | Prior to October 2019 | :x: *Deprecated* | [v1.0 Schema](https://github.com/MobilityData/gbfs-json-schema/tree/v1.0)| | | ||
|
|
||
| ### Full Version History | ||
| The complete GBFS version history is available on the [wiki](https://github.com/NABSA/gbfs/wiki/Complete-Version-History). | ||
|
|
||
| ## Specification Versioning | ||
| To enable the evolution of GBFS, including changes that would otherwise break backwards-compatibility with consuming applications, GBFS documentation is versioned. Semantic versions are established by a git tag in the form of `vX.Y` where `X.Y` is the version name. Multiple changes (commits) may be batched into a single new release. | ||
|
|
||
| A whole integer increase is used for breaking changes (MAJOR changes). A decimal increase is used for non-breaking changes (MINOR changes or patches). | ||
|
|
||
| Examples of breaking changes include: | ||
|
|
||
| * Adding or removing a required endpoint or field | ||
| * Changing the data type or semantics of an existing field | ||
|
|
||
| Examples of non-breaking changes include: | ||
|
|
||
| * Adding or removing an optional endpoint or field | ||
| * Adding or removing enum values | ||
| * Modifying documentation or spec language in a way that clarifies semantics or recommended practices | ||
|
|
||
|
|
||
| #### Version Release Cycles | ||
| - There is no strict limitation on the frequency of MAJOR releases, but the GBFS community aims to limit MAJOR releases to 2 or fewer in a 12 month period. To limit releases, multiple breaking changes SHOULD be batched together in a single release. | ||
| - There is no guideline to limit the number of MINOR releases. MINOR changes may be applied at any time. MINOR changes MAY be batched together in single release or released immediately, based on the needs of the community. | ||
| - GBFS documentation will include a list of current and supported MAJOR and MINOR versions. Supported versions SHALL NOT span more than two MAJOR versions. | ||
| ## Governance & Overview of the Change Process | ||
| GBFS is an open specification, developed and maintained by the community of producers and consumers of GBFS data. | ||
| The specification is not fixed or unchangeable. As the shared mobility industry evolves, it is expected that the specification will be extended by the GBFS community to include new features and capabilities over time. If you are new to engaging with the community on this repository, firstly welcome! Please identify which organization you represent when posting. | ||
|
|
@@ -127,27 +126,6 @@ Caution should be taken to avoid making changes to the spec that would render ex | |
| * **Speculative features are discouraged.** | ||
| Each new addition to the spec adds complexity. We want to avoid additions to the spec that do not provide additional value to the shared mobility end user. | ||
|
|
||
| ## Systems Catalog - Systems Implementing GBFS | ||
| There are now over 500 shared mobility systems publishing GBFS worldwide. This list contains all known systems publishing GBFS feeds and is maintained by the GBFS community. This is an incomplete list. If you have or are aware of a system that doesn’t appear on the list please add it. | ||
| If you would like to add a system, please fork this repository and submit a pull request. Please keep this list alphabetized by country and system name. | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It makes validation difficult if there's mix of versions. Seems like at least all feeds should be part of the same MAJOR version.