Merge pull request #4 from CityOfLosAngeles/master

billdirks · web-flow · commit a17acb9b59ff · 2019-06-06T15:03:02.000-07:00
Merging City of LA MDS dev branch into Ride Reports dev branch
diff --git a/.github/ISSUE_TEMPLATE/feature-request---proposal.md b/.github/ISSUE_TEMPLATE/feature-request---proposal.md
@@ -7,27 +7,34 @@ assignees: ''
 
 ---
 
-**Is your feature request related to a problem? Please describe.**
+### Is your feature request related to a problem? Please describe.
+
 A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
 
-**Describe the solution you'd like**
+### Describe the solution you'd like
+
 A clear and concise description of what you want to happen.
 
-**Is this a breaking change**
+### Is this a breaking change
+
 A breaking change would require consumers or implementors of the API to modify their code for it to continue to function (ex: renaming of a required field or the change in data type of an existing field). A non-breaking change would allow existing code to continue to function (ex: addition of an optional field or the creation of a new optional endpoint). 
 
-[  ] Yes, breaking
-[  ] No, not breaking
-[  ] I'm not sure
+* [ ] Yes, breaking
+* [ ] No, not breaking
+* [ ] I'm not sure
+
+### `Provider` or `agency`
 
-**`Provider` or `agency`**
 For which API is this feature being requested:
-[  ] `provider`
-[  ] `agency`
-[  ] both
 
-**Describe alternatives you've considered**
+* [ ] `provider`
+* [ ] `agency`
+* [ ] both
+
+### Describe alternatives you've considered
+
 A clear and concise description of any alternative solutions or features you've considered.
 
-**Additional context**
+### Additional context
+
 Add any other context or screenshots about the feature request here.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -1,18 +1,23 @@
-**Explain pull request**
+### Explain pull request
+
 Please provide a clear and concise reason for this pull request and the impact of the change
 
-**Is this a breaking change**
+### Is this a breaking change
+
 A breaking change would require consumers or implementors of the API to modify their code for it to continue to function (ex: renaming of a required field or the change in data type of an existing field). A non-breaking change would allow existing code to continue to function (ex: addition of an optional field or the creation of a new optional endpoint). 
 
-[  ] Yes, breaking
-[  ] No, not breaking
-[  ] I'm not sure
+* [ ] Yes, breaking
+* [ ] No, not breaking
+* [ ] I'm not sure
+
+### `Provider` or `agency`
 
-**`Provider` or `agency`**
 Which API(s) will this pull request impact:
-[  ] `provider`
-[  ] `agency`
-[  ] both
 
-**Additional context**
+* [ ] `provider`
+* [ ] `agency`
+* [ ] both
+
+### Additional context
+
 Add any other context or screenshots about the feature request here.
diff --git a/README.md b/README.md
@@ -14,8 +14,16 @@ The specification is a way to implement realtime data sharing, measurement and r
 
 Cities and regulators can choose best how to implement *Agency* and *Provider* either separately, concurrently, or by endpoint. 
 
+## Versions 
+
 The specification will be versioned using Git tags and [semantic versioning](https://semver.org/). See prior [releases](https://github.com/CityOfLosAngeles/mobility-data-specification/releases) and the [Release Guidelines](ReleaseGuidelines.md) for more information.
 
+Please note, you may be viewing a development copy of the Mobility Data Specification based on the current branch. Info about the latest release and all releases is below. 
+
+* [Latest Release](https://github.com/CityOfLosAngeles/mobility-data-specification/tree/master)
+
+* [All Releases](https://github.com/CityOfLosAngeles/mobility-data-specification/releases)
+
 ## Announcements 
 
 The City of Los Angeles is currently looking for feedback and comments on the draft versions. Comments can be made by making an Github Issue, while suggested changes can be made using a pull request. The rules and guidelines for the Los Angeles Dockless Bikeshare Systems / Pilot Program can be found on [Council Clerk Connect](https://cityclerk.lacity.org/lacityclerkconnect/index.cfm?fa=ccfi.viewrecord&cfnumber=17-1125).
diff --git a/ReleaseGuidelines.md b/ReleaseGuidelines.md
@@ -19,6 +19,26 @@ MDS uses [Semantic Versioning][semver]. Each release is associated with a [`git
 
 Given that MDS is stabilizing under MAJOR version `0.x` right now, it should be assumed that MINOR version increments (e.g. `0.2.0` to `0.3.0`) are equivalent to MAJOR version increments and may contain breaking changes.
 
+### Breaking vs. non-breaking changes
+
+Since MDS is used by a broad ecosystem of both API consumers and implementers, it needs a strict definition of what changes are “non-breaking” and are therefore allowed in PATCH releases.
+
+In the MDS spec, a breaking change is any change that requires either consumers or implementers to modify their code for it to continue to function correctly.
+
+Examples of breaking changes include:
+
+* Adding or removing a required endpoint or field
+* Adding or removing a request parameter
+* Changing the data type or semantics of an existing field, including clarifying previously-ambiguous requirements
+
+Examples of non-breaking changes include:
+
+* Adding or removing an optional endpoint or field
+* Adding or removing enum values
+* Modifying documentation or spec language that doesn't affect the behavior of the API directly
+
+One implication of this policy is that clients should be prepared to ignore the presence of unexpected fields in responses and unexpected values for enums. This is necessary to preserve compatibility between PATCH versions within the same MINOR version range, since optional fields and enum values can be added as non-breaking changes.
+
 ### Ongoing version support
 
 At this early stage, MDS will be moving relatively quickly with an eye toward stabilization rather than backwards-compatibility.
diff --git a/ReleaseNotes.md b/ReleaseNotes.md
@@ -1,3 +1,30 @@
+## 0.3.1
+
+> Released 2019-04-30
+
+This release represents a series of non-breaking changes and clarifications for provider, along with a number of agency bugfixes / changes. 
+
+**CHANGES**
+
+*_Provider_*
+* MDS Schema version fix.
+* [New release process](https://github.com/CityOfLosAngeles/mobility-data-specification/pull/264). Thanks @jfh for documenting, all for participating 
+* [Additional documentation around what is considered Breaking / Non-Breaking](https://github.com/CityOfLosAngeles/mobility-data-specification/pull/295). Thanks @rf-
+* [OPTIONS for version negotiation](https://github.com/CityOfLosAngeles/mobility-data-specification/pull/293). Thanks @billdirks
+* [Add Agency Drop off / pick up](https://github.com/CityOfLosAngeles/mobility-data-specification/pull/291). Thanks @margodawes 
+* [Explicitly allow associated_trip for any event type](https://github.com/CityOfLosAngeles/mobility-data-specification/pull/297)
+
+*_Agency_*
+* Change from UUIDv4 to just UUID. Thanks @karcass
+* Change Error Messages for State Machine validation. 
+* Update Pagination Rules 
+* Add Unregistered event. 
+* [Add Event Diagram](https://github.com/CityOfLosAngeles/mobility-data-specification/pull/258). Thanks @whereissean
+* [Removing 412 Responses](https://github.com/CityOfLosAngeles/mobility-data-specification/pull/258)
+* Add deregister and decomissioned events. Thanks @dirkdk 
+* [Remove 5 second Telemetry requirement](https://github.com/CityOfLosAngeles/mobility-data-specification/pull/261)
+* [Improve failure and error handling around Telemetry Data](https://github.com/CityOfLosAngeles/mobility-data-specification/pull/290)
+
 ## 0.3.0 
 
 > Released 2019-02-15
diff --git a/generate_schema/provider/status_changes.json b/generate_schema/provider/status_changes.json
@@ -123,7 +123,8 @@
                           "service_start",
                           "user_drop_off",
                           "rebalance_drop_off",
-                          "maintenance_drop_off"
+                          "maintenance_drop_off",
+                          "agency_drop_off"
                         ]
                       }
                     }
@@ -157,7 +158,8 @@
                         "enum": [
                           "service_end",
                           "rebalance_pick_up",
-                          "maintenance_pick_up"
+                          "maintenance_pick_up",
+                          "agency_pick_up"
                         ]
                       }
                     }
diff --git a/provider/README.md b/provider/README.md
@@ -41,6 +41,22 @@ Content-Type: application/vnd.mds.provider+json;version=0.3
 
 If an unsupported or invalid version is requested, the API must respond with a status of `406 Not Acceptable`. In which case, the response should include a body specifying a list of supported versions.
 
+A client can explicitly negotiate headers using the `OPTIONS` method to an MDS endpoint. For example, to check if `trips` supports either version `0.2` or `0.3` with a preference for `0.2`, the client would issue the following request:
+
+```http
+OPTIONS /trips/ HTTP/1.1 
+Host: provider.example.com 
+Accept: application/vnd.mds.provider+json;version=0.2,application/vnd.mds.provider+json;version=0.3;q=0.9
+```
+
+The response will include the most preferred supported version in the `Content-Type` header. For example, if only `0.3` is supported:
+
+```http
+Content-Type: application/vnd.mds.provider+json;version=0.3
+```
+
+The client can use the returned value verbatim as a version request in the `Accept` header.
+
 ### Response Format
 
 The response to a client request must include a valid HTTP status code defined in the [IANA HTTP Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml). It also must set the `Content-Type` header, as specified in the [Versioning](#Versioning) section.
@@ -276,7 +292,7 @@ Schema: [`status_changes` schema][sc-schema]
 | `event_time` | [timestamp][ts] | Required | Date/time that event occurred, based on device clock |
 | `event_location` | GeoJSON [Point Feature][geo] | Required | |
 | `battery_pct` | Float | Required if Applicable | Percent battery charge of device, expressed between 0 and 1 |
-| `associated_trip` | UUID | Required if Applicable | Trip UUID (foreign key to Trips API) required if `event_type_reason` is `user_pick_up` or `user_drop_off` |
+| `associated_trip` | UUID | Required if Applicable | Trip UUID (foreign key to Trips API), required if `event_type_reason` is `user_pick_up` or `user_drop_off`, or for any other status change event that marks the end of a trip. |
 
 ### Status Changes Query Parameters
 
@@ -295,12 +311,14 @@ When multiple query parameters are specified, they should all apply to the retur
 | | | `user_drop_off` | User ends reservation |
 | | | `rebalance_drop_off` | Device moved for rebalancing |
 | | | `maintenance_drop_off` | Device introduced into service after being removed for maintenance |
+| | | `agency_drop_off` | The administrative agency (ie, DOT) drops a device into the PROW using an admin code or similar | 
 | `reserved` | A customer reserves a device (even if trip has not started yet) | `user_pick_up` | Customer reserves device |
 | `unavailable` | A device is on the street but becomes unavailable for customer use | `maintenance` | A device is no longer available due to equipment issues |
 | | | `low_battery` | A device is no longer available due to insufficient battery |
 | `removed` | A device is removed from the street and unavailable for customer use | `service_end` | Device removed from street because service has ended for the day (if program does not operate 24/7) |
 | | | `rebalance_pick_up` | Device removed from street and will be placed at another location to rebalance service |
 | | | `maintenance_pick_up` | Device removed from street so it can be worked on |
+| | | `agency_pick_up` | The administrative agency (ie, DOT) removes a device using an admin code or similar |
 
 [Top][toc]
 
diff --git a/provider/status_changes.json b/provider/status_changes.json
@@ -314,7 +314,8 @@
                           "service_start",
                           "user_drop_off",
                           "rebalance_drop_off",
-                          "maintenance_drop_off"
+                          "maintenance_drop_off",
+                          "agency_drop_off"
                         ]
                       }
                     }
@@ -359,7 +360,8 @@
                         "enum": [
                           "service_end",
                           "rebalance_pick_up",
-                          "maintenance_pick_up"
+                          "maintenance_pick_up",
+                          "agency_pick_up"
                         ]
                       }
                     }

Original file line number	Diff line number	Diff line change
`@@ -123,7 +123,8 @@`
`123`	`123`	`"service_start",`
`124`	`124`	`"user_drop_off",`
`125`	`125`	`"rebalance_drop_off",`
`126`		`- "maintenance_drop_off"`
	`126`	`+ "maintenance_drop_off",`
	`127`	`+ "agency_drop_off"`
`127`	`128`	`]`
`128`	`129`	`}`
`129`	`130`	`}`
`@@ -157,7 +158,8 @@`
`157`	`158`	`"enum": [`
`158`	`159`	`"service_end",`
`159`	`160`	`"rebalance_pick_up",`
`160`		`- "maintenance_pick_up"`
	`161`	`+ "maintenance_pick_up",`
	`162`	`+ "agency_pick_up"`
`161`	`163`	`]`
`162`	`164`	`}`
`163`	`165`	`}`
Original file line number	Diff line number	Diff line change
`@@ -314,7 +314,8 @@`
`314`	`314`	`"service_start",`
`315`	`315`	`"user_drop_off",`
`316`	`316`	`"rebalance_drop_off",`
`317`		`- "maintenance_drop_off"`
	`317`	`+ "maintenance_drop_off",`
	`318`	`+ "agency_drop_off"`
`318`	`319`	`]`
`319`	`320`	`}`
`320`	`321`	`}`
`@@ -359,7 +360,8 @@`
`359`	`360`	`"enum": [`
`360`	`361`	`"service_end",`
`361`	`362`	`"rebalance_pick_up",`
`362`		`- "maintenance_pick_up"`
	`363`	`+ "maintenance_pick_up",`
	`364`	`+ "agency_pick_up"`
`363`	`365`	`]`
`364`	`366`	`}`
`365`	`367`	`}`