GTFS and GTFS-realtime decision process

gtfs-realtime/CHANGES.md

@@ -9,7 +9,7 @@ When a producer or consumer is interested in adding a new field to the GTFS Real
 ### *Experimental* fields
 
 1. If the community can come to consensus (a) that the proposed field seems useful and (b) on the type of the field (`optional` vs `repeated`, `string` vs `int` vs `bool`), then a field number will be allocated in the GTFS Realtime message and a note will be made in the [.proto file](/gtfs-realtime/proto/gtfs-realtime.proto) and documentation that this is an *experimental* field that may change in the future.
-      - Consensus is reached via a discussion and voting process that is the same as the below [Specification amendment process](#specification-amendment-process), but instead of unanimous consent only 80% yes votes are required for approval.
+      - Consensus is reached via a discussion and adopted through a voting process that is the same as the below [Specification amendment process](#specification-amendment-process).
       - GTFS Realtime producers and consumers that wish to use the new *experimental* field will re-generate their library using the .proto file with the new field (e.g., Google will update the [gtfs-realtime-bindings library](https://github.com/google/gtfs-realtime-bindings)), and start populating and parsing the field with live data.
       - Once we are satisfied that the *experimental* field is worthwhile and both producers and consumers are using the field, then we will follow the below [Specification amendment process](#specification-amendment-process) to officially add the field to the spec.
       - If the *experimental* field is not adopted via the [Specification amendment process](#specification-amendment-process) within 2 years of being approved as an *experimental* field, it will be deprecated by adding `[deprecated=true]` next to the field value in the [.proto file](/gtfs-realtime/proto/gtfs-realtime.proto) file.  By using `[deprecated=true]` (instead of `RESERVED`), producers and consumers that have already adopted the field do not have to remove it from use.  Additionally, the field may be "un-deprecated" in the future if it is approved in a subsequent vote following the [Specification amendment process](#specification-amendment-process) (e.g., when additional producers and/or consumers start using the field).
@@ -21,12 +21,12 @@ When a producer or consumer is interested in adding a new field to the GTFS Real
 1. Create pull request on https://github.com/google/transit. Pull request must contain an extended description of the patch. The creator of the pull request becomes the _advocate_.
 1. Once pull request is registered, it must be announced by its advocate in the [GTFS Realtime mailing list](https://groups.google.com/forum/#!forum/gtfs-realtime). Once announced, the pull request is considered a proposal.
   	- Since the advocate is a contributor, they must sign the [Contributor License Agreement](../CONTRIBUTING.md) before pull request can be accepted.
-1. The discussion of the proposal follows. Pull request comments should be used as the sole discussion forum.
+1. The discussion of the proposal follows, with a goal of reaching consensus. Pull request comments should be used as the sole discussion forum.
   	- The discussion lasts for as long as the advocate feels necessary, but must be at least 7 calendar days.
   	- The advocate is responsible for timely update of the proposal (i.e. pull request) based on the comments for which they agree to.
   	- At any point in time the advocate can claim proposal abandoned.
 1. The advocate can call for a vote on a version of the proposal at any point in time following the initial 7-day interval required for discussion.
-    - Before calling for a vote, at least one GTFS-realtime producer and one GTFS-realtime consumer should implement the proposed change. It is expected that the GTFS-realtime producer(s) include the change in a public-facing GTFS-realtime feed and provide a link to that data within the pull request comments, and that the GTFS-realtime consumer(s) provides a link in the pull request comments to an application that is utilizing the change in a non-trivial manner (i.e, it is supporting new or improved functionality).
+    - Before calling for a vote, at least one GTFS-realtime producer and one GTFS-realtime consumer must implement the proposed change. The GTFS-realtime producer(s) must include the change in a public-facing GTFS-realtime feed and provide a link to that data within the pull request comments, and the GTFS-realtime consumer(s) must provide a link in the pull request comments to an application that is utilizing the change in a non-trivial manner (i.e, it is supporting new or improved functionality).
     - When calling for a vote, the advocate should clearly state whether the vote is for official adoption of the field into the spec or for an experimental field.
 1. Vote lasts the minimum period sufficient to cover 7 full calendar days and 5 full Swiss business days. Vote ends at 23:59:59 UTC.
   	- The advocate should announce the specific end time at the start of the vote.
@@ -35,8 +35,10 @@ When a producer or consumer is interested in adding a new field to the GTFS Real
     If a voter changes her vote, it is recommended to do it by updating the original vote comment by striking through the vote and writing the new vote.
   	- Votes before the start of the voting period are not considered.
     - Opening and closing of votes must be announced on the [GTFS Realtime mailing list](https://groups.google.com/forum/#!forum/gtfs-realtime).
-1. The proposal is accepted if there is a unanimous consensus yes with at least 3 votes.
-  	- The proposer's vote does not count towards the 3 vote total. For example, if Proposer X creates a pull request and votes yes, and User Y and Z vote yes, this is counted as 2 total yes votes.
+1. The community holds a vote to determine whether the changes should be officially adopted. This vote follows an 80% majority rule, meaning at least 80% of votes must be in favor for it to pass.
+      - To be valid, the vote must include at least five contributors, with a minimum of two Producers and two Consumers. The voting period must last at least 14 days.
+      - Votes must be formatted as follows: “+1 or -1, Organization Name, Contributor Type (Consumer, Producer, or General Contributor), Link to Produced Feed or Consuming Application”
+  	- The advocate's vote does not count towards the vote total.
   	- Votes against shall be motivated, and ideally provide actionable feedback.
   	- If the vote has failed, then the advocate may choose to continue work on the proposal, or to abandon the proposal.
     Either decision of the advocate must be announced in the [GTFS Realtime mailing list](https://groups.google.com/forum/#!forum/gtfs-realtime).
@@ -61,6 +63,9 @@ Like GTFS before it, GTFS Realtime is primarily concerned with passenger informa
 #### Changes to the spec should be backwards-compatible.
 When adding features to the specification, we want to avoid making changes that will make existing feeds invalid. We don't want to create more work for existing feed publishers until they want to add capabilities to their feeds. Also, whenever possible, we want existing parsers to be able to continue to read the older parts of newer feeds. The conventions for extending Protocol Buffers will enforce backwards-compatibility to a certain extent. However, we wish to avoid semantic changes to existing fields that might break backwards-compatibility as well.
 
+#### Consensus means broad agreement, not unanimity.
+A data standards community must strive for consensus, which means broad and general agreement. Some may still not fully agree, but they assent. Contributors are encouraged to block consensus only if a proposal would contradict Guiding Principles or do great harm to transit riders or contributors. Consensus requires listening carefully, discussing respectfully, and using creative, collaborative problem solving to reach broad agreement. Unanimous consent would obstruct innovation and decisions that could offer tremendous benefit to transit agencies and riders around the world. Some Producers and Consumers represent the interests of more transit agencies and riders than others. Those who do not fully agree after discussion are encouraged to "stand aside," declare and explain their reservations or objections, and express their disagreement with a +0 vote. Advocates are encouraged to consider those reservations and objections seriously to keep the community as inclusive as possible.
+
 #### Speculative features are discouraged.
 Every new feature adds complexity to creating and reading of feeds. Therefore, we want to take care to only add features that we know to be useful. Ideally, any proposal will have been tested by generating data for a real transit system that uses the new feature and writing software to read and display it.
 

gtfs-realtime/proto/gtfs-realtime.proto

@@ -644,6 +644,7 @@ message Alert {
     CONSTRUCTION = 10;
     POLICE_ACTIVITY = 11;
     MEDICAL_EMERGENCY = 12;
+    SPECIAL_EVENT = 13;     // A special one-time or recurring event such as a parade, festival, performance, farmers market, or sporting event.
   }
   optional Cause cause = 6 [default = UNKNOWN_CAUSE];
 
@@ -1256,4 +1257,4 @@ message ReplacementStop {
 
   // The following extension IDs are reserved for private use by any organization.
   extensions 9000 to 9999;
-}
+}

gtfs-realtime/spec/en/reference.md

@@ -398,6 +398,7 @@ Cause of this alert.
 | **CONSTRUCTION** |
 | **POLICE_ACTIVITY** |
 | **MEDICAL_EMERGENCY** |
+| **SPECIAL_EVENT** |
 
 ## _enum_ Effect
 

gtfs-realtime/spec/en/service-alerts.md

@@ -44,6 +44,7 @@ What is the cause of this alert? You may specify one of the following:
 *   Construction
 *   Police activity
 *   Medical emergency
+*   Special Event
 
 ## Effect
 

gtfs/Governance/change-process.md

@@ -33,7 +33,7 @@ This process guides how the community proposes, reviews, and adopts [Functional
 * A proposal is submitted by opening a Pull Request in the GTFS Repository.   
 * The community engages in discussions to refine the proposal. This period must last at least 7 days.
 * The [Contributors](roles.md/#contributors) and the [Maintainer](roles.md/#maintainer) review the proposed changes. This period must last at least 7 days.  
-* Before testing, the community holds a vote to confirm unanimous consensus on the proposal. This means all participating voters must be in favor. For the vote to be valid, it must include at least five contributors, with a minimum of two Producers and two Consumers. The voting period must last at least 14 days. 
+* Before testing, the community confirms there is consensus on the proposal, as described in Guiding Principles. This does not mean all participating voters must be in favor. For the vote to be valid, it must include at least five contributors, with a minimum of two Producers and two Consumers. The voting period must last at least 14 days. 
 * [First Adopters](roles.md/#first-adopter) test the proposed changes.   
 * The community holds a vote to determine whether the changes should be officially adopted. This vote follows an 80% majority rule, meaning at least 80% of votes must be in favor for it to pass. To be valid, the vote must include at least five contributors, with a minimum of two Producers and two Consumers. The voting period must last at least 14 days.
 * Finally, changes are implemented into the specification.

gtfs/Governance/guiding-principles.md

@@ -15,4 +15,7 @@ GTFS is primarily concerned with passenger information. That is, the spec should
 When adding features to the specification, we want to avoid making changes that will make existing feeds invalid. We don't want to create more work for existing feed publishers until they want to add capabilities to their feeds. Also, whenever possible, we want existing parsers to be able to continue to read the older parts of newer feeds.
 
 **Speculative features are discouraged**  
-Every new feature adds complexity to the creation and reading of feeds. Therefore, we want to take care to only add features that we know to be useful. Ideally, any proposal will have been tested by generating data for a real transit system that uses the new feature and writing software to read and display it. Note that the GTFS readily allows for extensions to the format through the addition of extra columns and files that are ignored by the official parsers & validators, so proposals can be easily prototyped and tested on existing feeds.
+Every new feature adds complexity to the creation and reading of feeds. Therefore, we want to take care to only add features that we know to be useful. Ideally, any proposal will have been tested by generating data for a real transit system that uses the new feature and writing software to read and display it. Note that the GTFS readily allows for extensions to the format through the addition of extra columns and files that are ignored by the official parsers & validators, so proposals can be easily prototyped and tested on existing feeds.
+
+**Consensus means broad agreement, not unanimity**
+A data standards community must strive for consensus, which means broad and general agreement. Some may still not fully agree, but they assent. Contributors are encouraged to block consensus only if a proposal would contradict Guiding Principles or do great harm to transit riders or contributors. Consensus requires listening carefully, discussing respectfully, and using creative, collaborative problem solving to reach broad agreement. Unanimous consent would obstruct innovation and decisions that could offer tremendous benefit to transit agencies and riders around the world. Some Producers and Consumers represent the interests of more transit agencies and riders than others. Those who do not fully agree after discussion are encouraged to "stand aside," declare and explain their reservations or objections, and express their disagreement with a +0 vote. Advocates are encouraged to consider those reservations and objections seriously to keep the community as inclusive as possible.