Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Versioning and Long Term Support #386

Merged
merged 13 commits into from
Dec 15, 2021
Merged

Versioning and Long Term Support #386

Show file tree
Hide file tree
Changes from 12 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
894e064
Update README.md
Nov 4, 2021
4557991
fix typos
Nov 4, 2021
feab2e9
Update README.md
Nov 4, 2021
33be600
Update name
Nov 4, 2021
7201e34
Update README.md
Nov 4, 2021
704511d
Update README.md
Nov 4, 2021
d65acdc
Revert "Update README.md"
Nov 8, 2021
3867561
Revert "Update README.md"
Nov 8, 2021
ceab1fe
Revert "Update name"
Nov 8, 2021
46d2c2e
Revert "Update README.md"
Nov 8, 2021
8db1d52
Version history link
Nov 8, 2021
d58b249
Versioning revisions
Nov 9, 2021
c440bb3
fix typo
Nov 30, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 53 additions & 75 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
* [Read the Spec & Version History](#read-the-spec--version-history)
* [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)
Expand All @@ -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: [sharedmobility@mobilitydata.org](mailto:sharedmobility@mobilitydata.org)
## Current Version
**The current release is [v2.2](https://github.com/NABSA/gbfs/blob/v2.2/gbfs.md)**


## Read the Spec & Version History

* [v1.0](https://github.com/NABSA/gbfs/blob/v1.0/gbfs.md)
* 2019 December 20 - GBFS copyright [transfered to NABSA](https://github.com/NABSA/gbfs/commit/b1260b9c59eeff810a62e0aedc72ce1d4fb8f3ab)
* 2015 November 05 - GBFS V1.0 Adopted by NABSA board - [Original draft spec in a Google doc](https://docs.google.com/document/d/1BQPZCKpem4-n6lUQDD4Mi8E5hNZ0-lhY62IVtWuyhec/edit#heading=h.ic7i1m4gcev7) (reference only)
* 2015 August - Latest changes incorporated and name change to GBFS (comments from Motivate, 8D, others)
* 2015 June - Proposed refinements (prepared by Jesse Chan-Norris on behalf of Motivate)
* 2014 September 07 - Draft specification presented by Mitch Vars at 1st annual [NABSA](https://nabsa.net/) conference, Pittsburgh, PA
* [v1.1-RC (Release Candidate)](https://github.com/NABSA/gbfs/blob/v1.1-RC/gbfs.md)
* [#25](https://github.com/NABSA/gbfs/pull/25) - Add deep links for iOS, Android, and web apps
* [#181](https://github.com/NABSA/gbfs/pull/181) - Add `feed_contact_email` field to `system_information.json`
* [#188](https://github.com/NABSA/gbfs/pull/188) - GBFS documentation versioning and and feed conformance (adds `gbfs_versions.json`)
* [v1.1](https://github.com/NABSA/gbfs/blob/v1.1/gbfs.md)
* [#25](https://github.com/NABSA/gbfs/pull/25) - Add deep links for iOS, Android, and web apps
* [#181](https://github.com/NABSA/gbfs/pull/181) - Add `feed_contact_email` field to `system_information.json`
* [#188](https://github.com/NABSA/gbfs/pull/188) - GBFS documentation versioning and and feed conformance (adds `gbfs_versions.json`)
* [v2.0-RC (Release Candidate)](https://github.com/NABSA/gbfs/blob/v2.0-RC/gbfs.md)
* [#182](https://github.com/NABSA/gbfs/pull/182) - Require `license_url`, add attribution fields
* [#189](https://github.com/NABSA/gbfs/pull/189) - Require autodiscovery gbfs.json file, define feed names
* [#195](https://github.com/NABSA/gbfs/pull/195) - Clarify `num_bikes_available` and `num_docks_available`
* [#196](https://github.com/NABSA/gbfs/pull/196) - Change boolean from 1/0 to true/false
* [#147](https://github.com/NABSA/gbfs/pull/147) - Rotate `bike_id` on `free_bike_status`
* [v2.0](https://github.com/NABSA/gbfs/blob/v2.0/gbfs.md)
* [#189](https://github.com/NABSA/gbfs/pull/189) - Require autodiscovery gbfs.json file, define feed names
* [#195](https://github.com/NABSA/gbfs/pull/195) - Clarify `num_bikes_available` and `num_docks_available`
* [#196](https://github.com/NABSA/gbfs/pull/196) - Change boolean from 1/0 to true/false
* [#147](https://github.com/NABSA/gbfs/pull/147) - Rotate `bike_id` on `free_bike_status`
* [v2.1-RC (Release Candidate)](https://github.com/NABSA/gbfs/blob/v2.1-RC/gbfs.md)
* [#136](https://github.com/NABSA/gbfs/pull/136) - Add vehicle type definitions
* [#219](https://github.com/NABSA/gbfs/pull/219) - Add geofencing, virtual station, and dockless support
* [v2.1-RC2 (Release Candidate)](https://github.com/NABSA/gbfs/blob/v2.1-RC2/gbfs.md)
* [#261](https://github.com/NABSA/gbfs/pull/261) - Aggregate available vehicle_types at a station
* [#252](https://github.com/NABSA/gbfs/pull/252) - Extend system_pricing_plans.json
* [v2.1](https://github.com/NABSA/gbfs/blob/v2.1/gbfs.md)
* [#136](https://github.com/NABSA/gbfs/pull/136) - Add vehicle type definitions
* [#219](https://github.com/NABSA/gbfs/pull/219) - Add geofencing, virtual station, and dockless support
* [#261](https://github.com/NABSA/gbfs/pull/261) - Aggregate available vehicle_types at a station
* **[v2.2 Current Version](https://github.com/NABSA/gbfs/blob/v2.2/gbfs.md)**
* [#252](https://github.com/NABSA/gbfs/pull/252) - Extend system_pricing_plans.json
* [v2.3-RC (Release Candidate)](https://github.com/NABSA/gbfs/blob/v2.3-RC/gbfs.md)
* [#329](https://github.com/NABSA/gbfs/pull/329) - Add vehicle drop off restrictions
* [#330](https://github.com/NABSA/gbfs/pull/330) - Adding vehicle icons & brand information
* [#331](https://github.com/NABSA/gbfs/pull/331) - Reserve time for vehicle types and pricing plans
* [#335](https://github.com/NABSA/gbfs/pull/335) - Add pricing plans to vehicle types
* [#336](https://github.com/NABSA/gbfs/pull/336) - Add fields for terms and privacy policy
* [#340](https://github.com/NABSA/gbfs/pull/340) - Add field to designate stations that support vehicle charging
* [v3.0-RC (Release Candidate)](https://github.com/NABSA/gbfs/blob/master/gbfs.md)
* [#182](https://github.com/NABSA/gbfs/pull/182) - Require `license_url`, add attribution fields

## 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 | Q2, 2021 | :construction:   *In Development* |
mplsmitch marked this conversation as resolved.
Show resolved Hide resolved

### 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: &nbsp; *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: &nbsp; *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: &nbsp; *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: &nbsp; *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: &nbsp; *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.
Expand Down Expand Up @@ -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.

## 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 the MAJOR releases to 2 or fewer 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. MINOR changes may be batched or released immediately, at the discretion of the pull request author and advocate.
* GBFS documentation will include a designated long-term support (LTS) branch. The LTS branch would maintain its LTS status for at least 2 years, after which a new LTS release and branch would be designated. The LTS branch will be determined according to the GBFS voting process. Non-breaking changes (MINOR) will be applied to the LTS branch when relevant.

## 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.
Expand Down
25 changes: 10 additions & 15 deletions gbfs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ This document explains the types of files and data that comprise the General Bik

# Reference version

This documentation refers to **v3.0-RC (release candidate)**.<br>
This documentation refers to **v3.0-Draft (future version)**.<br>
**For the current version see [**version 2.2**](https://github.com/NABSA/gbfs/blob/v2.2/gbfs.md).** For past and upcoming versions see the [README](README.md#read-the-spec--version-history).

## Terminology
Expand All @@ -15,7 +15,6 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
## Table of Contents

* [Introduction](#introduction)
* [Version Endpoints](#version-endpoints)
* [Term Definitions](#term-definitions)
* [Files](#files)
* [Accessibility](#accessibility)
Expand Down Expand Up @@ -47,18 +46,6 @@ This specification has been designed with the following concepts in mind:

The specification supports real-time travel advice in GBFS-consuming applications.

## 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 />

GBFS Best Practice defines that:<br />

_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. It is not necessary to support more than one _MINOR_ release of the same _MAJOR_ release group because _MINOR_ releases are backwards-compatible. See [specification versioning](https://github.com/NABSA/gbfs/blob/master/README.md#specification-versioning)<br />

_GBFS consumers_ SHOULD, at a minimum, support the current LTS branch. It is highly RECOMMENDED that GBFS consumers support later releases.<br />

Default GBFS feed URLs, e.g. `https://www.example.com/data/gbfs.json` or `https://www.example.com/data/fr/system_information.json` MUST direct consumers to the feed that conforms to the current LTS documentation branch.

## Term Definitions

This section defines terms that are used throughout this document.
Expand Down Expand Up @@ -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 />
Copy link

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.

Copy link
Contributor

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?

Copy link
Collaborator Author

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.


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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That would be useful to add, thanks!


GBFS producers SHOULD provide endpoints that conform to the current MAJOR version release within 180 days of a new MAJOR version release. It is not necessary to support more than one MINOR release of the same MAJOR release group because MINOR releases are backwards-compatible. See [specification versioning](https://github.com/NABSA/gbfs/blob/master/README.md#specification-versioning).

### Auto-Discovery

Publishers SHOULD implement auto-discovery of GBFS feeds by linking to the location of the `gbfs.json` auto-discovery endpoint.

* The location of the auto-discovery file SHOULD be provided in the HTML area of the shared mobility landing page hosted at the URL specified in the URL field of the `system_infomation.json` file.
* The location of the auto-discovery file SHOULD be provided in the HTML area of the shared mobility landing page hosted at the URL specified in the `url` field of the `system_infomation.json` file.
* This is referenced via a _link_ tag with the following format:
* `<link rel="gbfs" type="application/json" href="https://www.example.com/data/gbfs.json" />`
* References:
Expand Down