Adding new fields to GTFS Realtime¶
When a producer or consumer is interested in adding a new field to the GTFS Realtime specification, they should open a new issue on the GTFS Realtime GitHub repository describing the proposed field and announce this new field (including a link to the issue) on the GTFS Realtime mailing list.
Specification amendment process¶
- Create a git branch with update of all relevant parts of protocol definition, specification and documentation files (except for translations).
- 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.
- Once pull request is registered, it must be announced by its advocate in the GTFS Realtime mailing list. Once announced, the pull request is considered a proposal.
- Since the advocate is a contributor, they must sign the Contributor License Agreement before pull request can be accepted.
- The discussion of the proposal follows. 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.
- 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).
- 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.
- 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.
- During voting period only editorial changes to the proposal are allowed (typos, wording may change as long as it does not change the meaning).
- Anyone is allowed to vote yes/no in a form of comment to the pull request, and votes can be changed until the end of the voting period. 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.
- 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.
- 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 mailing list.
- If the advocate continues the work on proposal then a new vote can be called for at any point in time.
- Any pull request remaining inactive for 30 calendar days will be closed. When a pull request is closed, the corresponding proposal is considered abandoned. The advocate may reopen the pull request at any time if they wish to continue or maintain the conversation.
- Note that the advocate may choose to implement the feature as an custom extension instead of part of the official spec.
- If the proposal is accepted:
- Google is committed to merging the voted upon version of the pull request (provided that the contributors have signed the CLA, and performing the pull request within 5 business days.
- Google is committed to timely updating https://github.com/google/gtfs-realtime-bindings repository. Commits to gtfs-realtime-bindigs that are a result of a proposal, should reference the pull request of the proposal.
- Translations must not be included into the original pull request. Google is responsible for eventually updating relevant translations into supported languages, but pure translation pull requests from the community are welcome and will be accepted as soon as all editorial comments are addressed.
If the community can come to consensus (a) that the proposed field seems useful and (b) on the type of the field (
bool), then a field number will be allocated in the GTFS Realtime message and a note will be made in the .proto file 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, but instead of unanimous consent only 80% yes votes are required for approval.
- 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), 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 to officially add the field to the spec.
- If the experimental field is not adopted via the 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 file. By using
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 (e.g., when additional producers and/or consumers start using the field).
If the new field is considered specific to a single producer or there is dispute over the data type, then we will assign a custom extension to the producer so they can use the field in their own feed. When possible we should avoid extensions and add fields useful to many agencies to the main specification to avoid fragmentation and extra work for consumers to support various extensions to the spec.