Reform proposal to add CrowdLevel

.github/workflows/validate-proto.yml

@@ -0,0 +1,25 @@
+name: Validate GTFS-realtime .proto file
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up JDK 1.8
+      uses: actions/setup-java@v1
+      with:
+        java-version: 1.8
+        server-id: github # Value of the distributionManagement/repository/id field of the pom.xml
+        settings-path: ${{ github.workspace }} # location for the settings.xml file
+    - name: Install Protoc
+      uses: arduino/setup-protoc@master
+    - name: Compile Java bindings
+      run: protoc --java_out=gtfs-realtime/proto gtfs-realtime/proto/gtfs-realtime.proto

gtfs-realtime/spec/en/examples/README.md

@@ -1,4 +1,11 @@
+### Plain text feed examples
+
 The following examples show a textual representation of feeds. During development it is more convenient to produce ASCII protocol buffer output for easier debugging. You can compare your text output with these examples to check for the validity of data.
 
 *   [Alerts](alerts.asciipb)
 *   [Trip update (full dataset)](trip-updates-full.asciipb)
+
+### Migration guides
+
+The following migration guides can help consumers and producers transition from "unofficial" practices to new "official" features of the spec:
+* [Transition from ADDED to DUPLICATED trips](migration-duplicated.md) - A duplicated trip is new trip that is the same as an existing scheduled trip except for service start date and time. This [migration guide](migration-duplicated.md) defines how existing producers and consumers that were using the `ADDED` enumeration to represent duplicated trips should transition to the `DUPLICATED` enumeration. 

gtfs-realtime/spec/en/examples/migration-duplicated.md

@@ -0,0 +1,104 @@
+## Migration Guide - Transition from ADDED to DUPLICATED trips 
+
+The GTFS-realtime `trip.schedule_relationship` of `DUPLICATED` represents a new trip that is the same as an existing scheduled trip except for service start date and time. 
+
+This migration guide defines how existing producers and consumers that were using the `ADDED` enumeration to represent duplicated trips should transition to the `DUPLICATED` enumeration. The goal is to minimize disruption to producers and consumers during the transition. 
+
+*If you are a producer or consumer that has **not** used the `ADDED` enumeration to describe duplicated trips, no action is required - you can produce/consume `DUPLICATED` trips without producing/consuming any `ADDED` entities.* 
+
+For a full history of the `DUPLICATED` enumeration, see the [`DUPLICATED` proposal on GitHub](https://github.com/google/transit/pull/221).
+
+### Using ADDED and DUPLICATED entities in same feed
+
+#### Producers
+
+If you are a producer who has been using the `ADDED` enumeration for duplicated trips, to avoid disruption to existing consumers it is recommended that you continue to produce `ADDED` entities for these trips but also add `DUPLICATED` entities for the same trip.  
+
+However, to prevent consumers from accidentally adding the same trip twice, the entities referencing the same trip **must** be linked using the same `trip_id`. You can link the two entities in **one** of two ways:  
+
+ 1. `trip.trip_id` of both entities **must** be the same, OR
+ 2. `trip.trip_id` of the `ADDED` trip **must** be the same as the `DUPLICATED` trip `trip_properties.trip_id`
+
+Here's an example of the first option (1) to duplicate GTFS `trip_id 1`, with the `trip.trip_id` matching in the `ADDED` and `DUPLICATED` entities:
+
+~~~
+entity {
+  id: "ei0"
+  trip_update {
+    trip: {
+      trip_id: "1" // <-- trip_id from static GTFS to copy
+      schedule_relationship: ADDED
+      start_date: "20200821" // <-- New trip date
+      start_time: "11:30:00" // <-- New trip time
+    }
+    stop_time_update {
+	...
+    }
+  }
+}
+
+entity {
+  id: "ei10"
+  trip_update {
+    trip: {
+      trip_id: "1" // <-- trip_id from static GTFS to copy
+      schedule_relationship: DUPLICATED
+    }
+    trip_properties {
+      trip_id: "NewTripId987" // <-- New trip_id unique to this trip
+      start_date: "20200821"  // <-- New trip date
+      start_time: "11:30:00"  // <-- New trip time
+    }
+    stop_time_update {
+	...
+    }
+  }
+}
+~~~
+
+Here's an example of the second option (2) to duplicate GTFS `trip_id 1`, with the `trip.trip_id` of the `ADDED` trip matching the `DUPLICATED` trip `trip_properties.trip_id`:
+
+~~~
+entity {
+  id: "ei0"
+  trip_update {
+    trip: {
+      trip_id: "NewTripId987" // <-- New trip_id unique to this trip
+      schedule_relationship: ADDED
+      start_date: "20200821" // <-- New trip date
+      start_time: "11:30:00" // <-- New trip time
+    }
+    stop_time_update {
+	...
+    }
+  }
+}
+
+entity {
+  id: "ei10"
+  trip_update {
+    trip: {
+      trip_id: "1" // <-- trip_id from static GTFS to copy
+      schedule_relationship: DUPLICATED
+    }
+    trip_properties {
+      trip_id: "NewTripId987" // <-- Matches the ADDED trip.trip_id
+      start_date: "20200821"  // <-- New trip date
+      start_time: "11:30:00"  // <-- New trip time
+    }
+    stop_time_update {
+	...
+    }
+  }
+}
+~~~
+
+It is suggested that you notify existing consumers (e.g., via a developer mailing list) that the use of `ADDED` for duplicated trips is being deprecated by a set deadline and that consumers should start consuming the `DUPLICATED` trips instead. The above strategy being used to match `ADDED` and `DUPLICATED` trip entities should also be mentioned and a link to this migration guide should be included. After the deadline passes, you can remove the `ADDED` entities from your feed and publish only the `DUPLICATED` entities for duplicated trips.
+
+#### Consumers
+
+As mentioned above, producers will transition from `ADDED` to `DUPLICATED` enumerations by initially publishing two entities for each duplicated trip, using one of the two above options for matching IDs between the entities. 
+
+Therefore, when a consumer implements support for `DUPLICATED` trips, it is important that consumers:
+ 1. Ignore any `ADDED` trips that have the same `trip.trip_id` as a `DUPLICATED` trip `trip.trip_id`
+ 1. Ignore any `ADDED` trips that have the same `trip.trip_id` as a `DUPLICATED` trip `trip_properties.trip_id`