Add new governance files

Sergiodero · Sergiodero · commit 1016824ebdc8 · 2025-02-12T16:20:15.000-05:00
diff --git a/docs/en/community/governance/schedule/change-process.md b/docs/en/community/governance/schedule/change-process.md
diff --git a/docs/en/community/governance/schedule/change-types.md b/docs/en/community/governance/schedule/change-types.md
@@ -0,0 +1,62 @@
+# Change Types
+
+Proposed changes to the specification are categorized based on their impact on its functionality and interpretation. Each category follows a specific process before being officially adopted into GTFS.
+
+<img class="center" width="100%" height="100%" src="../../../../assets/governance-change-types.png" alt="GTFS Governance Change Types"> 
+
+## 1. Functional changes
+
+Functional changes refers to modifications that significantly affect specification functionalities. These changes typically require testing and include adding new elements (files, fields, enums) or modifying existing ones. Such changes have to follow the complete specification change process in order to be officially adopted.
+
+Past Examples:
+
+* [PR #405](https://github.com/google/transit/pull/405) adds two new files networks.txt and route_networks.txt.  
+* [PR #385](https://github.com/google/transit/pull/385) adds a new option for the field fare_media_type in fare_media.txt.
+
+## 2. Non-Functional changes
+
+Non-functional changes refer to important updates to the specification that do not significantly affect functionalities. These changes typically do not require testing and they include the update of requirements, the addition or modification of best practices and any non-editorial modification to the governance framework.
+
+### Requirement updates 
+
+Modifications that do not introduce substantial changes to existing functionalities but affect the implementation and compliance of current elements within the specification. This includes, updates to presence types for files and fields, and adjustments to file requirements. 
+
+* Past Examples:   
+    * [PR #472](https://github.com/google/transit/pull/472) changes stops.txt presence from Required to Conditionally Required.  
+    * [PR #379](https://github.com/google/transit/pull/379) adds a new requirement for all GTFS datasets.
+
+### Governance
+
+Changes to the processes and guidelines governing the management of the specification include updates to the amendment process, modifications to roles and responsibilities, revisions to contribution guidelines, and adjustments to any document related to the governance framework. These updates ensure clear and effective management practices.
+
+* Past Examples:   
+    * [PR #387](https://github.com/google/transit/pull/387) updates the specification change process to switch from Swiss business days to calendar days only.
+
+### Best practices
+
+Changes enhancing specific parts of the specification by incorporating recommendations through the use of "should" statements. These updates provide guidance on preferred approaches or methods, encouraging users to follow best practices while maintaining flexibility in the specification's application.
+
+* Past Examples:  
+    * [PR #485](https://github.com/google/transit/pull/485) creates a new best practice to add that headsigns are recommended.  
+    * [PR #406](https://github.com/google/transit/pull/406) introduces the Dataset Publishing guidelines and Practice Recommendations for all files into the specification
+
+## 3. Documentation maintenance
+
+Specification changes that focus on maintaining the documentation are made to improve the specification's clarity, accuracy, and presentation without altering its semantics or functionality. These updates may involve expanding existing content to provide clearer descriptions while preserving the specification’s current interpretation. These changes require a review, but they can be adopted without the need of a vote.
+
+### Editorial 
+
+These involve correcting grammar, spelling, punctuation, typographical errors, and outdated links. They also include documenting adopted changes in the revision history and making formatting adjustments. Editorial updates for Governance-related files are included in this category.
+
+* Past Examples:  
+    * [PR #506](https://github.com/google/transit/pull/505) Updates the revision history for the month of September 2024  
+    * [PR #361](https://github.com/google/transit/pull/361) Fixes a broken link in fare\_rules.txt  
+    * [PR #412](https://github.com/google/transit/pull/412) Changes the location of an existing misplaced requirement.
+
+### Clarifications & Examples
+
+Clarifications expand on specific points to improve understanding, add necessary context, and provide examples that demonstrate how to apply the specification. These updates ensure users can interpret and follow it correctly without altering its intended functionality.
+
+* Past Examples:  
+    * [PR #443](https://github.com/google/transit/pull/443) adds links to example pages that supplement the information in the reference document  
+    * [PR #426](https://github.com/google/transit/pull/426) modifies the definition of fare products to reflect its intended use.
diff --git a/docs/en/community/governance/schedule/guiding-principles.md b/docs/en/community/governance/schedule/guiding-principles.md
@@ -0,0 +1,18 @@
+# Guiding principles
+
+In order to preserve the original vision of GTFS, a number of guiding principles have been established to take into consideration when changing the specification:
+
+**Feeds should be easy to create and edit**  
+We chose CSV as the basis for the specification because it's easy to view and edit using spreadsheet programs and text editors, which is helpful for smaller agencies. It's also straightforward to generate from most programming languages and databases, which is good for publishers of larger feeds.
+
+**Feeds should be easy to parse**  
+Feed readers should be able to extract the information they're looking for with as little work as possible. Changes and additions to the feed should be as broadly useful as possible, to minimize the number of code paths that readers of the feed need to implement. (However, making creation easier should be given precedence, since there will ultimately be more feed publishers than feed readers.)
+
+**The spec is about passenger information**  
+GTFS is primarily concerned with passenger information. That is, the spec should include information that can help power tools for riders, first and foremost. There is potentially a large amount of operations-oriented information that transit agencies might want to transmit internally between systems. GTFS is not intended for that purpose and there are potentially other operations-oriented data-standards that may be more appropriate.
+
+**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.
+
+**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.
diff --git a/docs/en/community/governance/schedule/intro.md b/docs/en/community/governance/schedule/intro.md
@@ -0,0 +1,28 @@
+# Introduction
+
+The GTFS standard is not set in stone; it is an open specification developed and maintained by a community of transit agencies, developers, and other stakeholders who actively use it. As this community of GTFS data producers and consumers continues to evolve, proposals for extending the specification to support new capabilities are expected. To manage this process, a GTFS governance framework has been established.
+
+GTFS governance refers to the framework that guides how the GTFS is maintained, updated, and developed. It encompasses the rules and processes that the community has established to guide decision-making, ensuring that GTFS remains an open and collaborative data standard.
+
+The governance framework for GTFS is composed of the following elements:
+
+<img class="center" width="560" height="100%" src="../../../../assets/governance-intro-pillars.png" alt="Main elements of GTFS Governance">
+
+* Guiding principles  
+* Roles and responsibilities  
+* Change types  
+* Change process
+
+The GTFS Change Process is the procedure by which modifications or additions to GTFS are proposed, discussed, and approved by the community. This process ensures that the specification evolves in a stable, predictable and collaborative way.
+
+## What is a specification change?
+
+A change refers to any proposed modification to the GTFS documentation hosted in the [Google/transit repository](https://github.com/google/transit). Such changes may include adding new functionalities, updating existing files or fields, clarifying guidelines, or improving examples. **In essence, proposing a change means proposing to change the content of any file associated with the documentation, most notably the Reference.md file, to enhance or expand the specification.**
+
+## How can I start participating?
+
+Anyone can contribute to the development of GTFS. Typically, anyone with a suggestion or idea for improving the specification follows the steps outlined in the GTFS Change Process to refine and advance their proposal.
+
+To navigate the process effectively, it's important to understand the different types of changes which determine the specific steps that need to be taken. Thus, it’s recommended that contributors familiarize themselves with these change categories, as well as the roles and responsibilities, to better understand their participation and involvement.
+
+
diff --git a/docs/en/community/governance/schedule/roles.md b/docs/en/community/governance/schedule/roles.md
@@ -0,0 +1,76 @@
+# Roles and Responsibilities
+
+The community is composed of two main stakeholder categories: Contributors and the Maintainer. 
+
+<img class="center" width="800" height="100%" src="../../../../assets/governance-roles-1.png" alt="GTFS Governance Roles"> 
+
+## Contributors
+
+Anyone can become a Contributor by participating in discussions within the official GTFS repository, regardless of their technical skills or experience with GTFS.
+
+**Responsibilities**
+
+* Track development progress, participate in discussions, and review Issues and Pull Requests.   
+* Express their views with respect and understanding, adhering to the GTFS Guiding Principles.
+
+### Contributor Types
+
+#### Producers
+
+A GTFS Producer is an individual or organization responsible for generating GTFS data. This may include transit agencies, data vendors, aggregators, or planners.
+
+* If an individual or organization assigns GTFS feed production to another party, only one of them can be recognized as the Producer.  
+* To vote, Producers must reference the GTFS feed they represent to confirm their role as Producer.  
+* In the case where a contributor is both a Consumer and Producer, they can only count as one, thus they must select a single role to represent during testing and voting.
+
+#### Consumers
+
+A GTFS Consumer is an individual or organization that ingests GTFS data, typically to provide and distribute rider-facing transit information through platforms such as software applications.
+
+* In some cases, contributors may consume GTFS data for research, data analysis, operations, planning, etc. However, they are considered Consumers only if their work is publicly accessible or shared in a public-facing context.  
+* To vote, consumers must reference the GTFS consuming application they represent to confirm their role as Consumer.  
+* In the case where a contributor is both a Consumer and Producer, they can only count as one, thus they must select a single role to represent during testing and voting.
+
+#### General Contributors
+
+Individuals or organizations that do not qualify as either Producers or Consumers are considered as General Contributors or simply referred to as Contributors. 
+
+## Maintainer
+
+The Maintainer supports and facilitates the specification change process, and their role as an impartial facilitator is to guide the community toward making consensus-driven decisions. MobilityData currently serves as the Maintainer of GTFS. 
+
+**Responsibilities**:
+
+* Assist Advocates in facilitating discussions when needed.   
+* Provide constructive feedback and recommendations to help refine proposals.  
+* Check that the terminology used in specification proposals aligns with the one used in the official specification.  
+* Ensure all GTFS Contributors follow the governance framework by monitoring and moderating community interactions.  
+* Can act as the Advocate for proposals.  
+* Assume the role of the Advocate if they become unresponsive at any point.  
+* Cannot participate in any voting process. 
+
+## Special roles
+
+General Contributors, Producers, Consumers and the Maintainer can take on special roles to support the development of specification changes. The Advocate and First Adopter roles are particularly critical for the Change Process to function effectively.
+
+
+<img class="center" width="100%" height="100%" src="../../../../assets/governance-roles-2.png" alt="GTFS Governance Special Roles"> 
+
+### Advocate
+
+An Advocate proposes a change to the official specification by publishing a Pull Request. Anyone can be an Advocate.
+
+**Responsibilities**
+
+* Follows the appropriate Change Process for the proposed change.  
+* Request assistance from the Maintainer if necessary. 
+
+### First Adopter
+
+First Adopters are Producers and Consumers who implement and test proposed changes as agreed upon in discussions. 
+
+**Responsibilities**:
+
+* Communicate any modifications or challenges that arise during testing.  
+* Publicly publish proof of implementation in the Pull Request.  
+* A consumer acting as a first adopter must guarantee that the GTFS data is tested using a rider-facing application. 
diff --git a/docs/en/community/governance/schedule/test-process-overview.md b/docs/en/community/governance/schedule/test-process-overview.md
@@ -0,0 +1,81 @@
+# Change Process Overview
+
+The specification change process guides how the community proposes, reviews, and adopts changes to the specification in the [GTFS Repository](https://github.com/google/transit/pulls). 
+
+The specification change process is categorized into 3 tracks according to the three change types: functional changes, non-functional changes, and documentation maintenance. The change process is separated into 2 stages: 
+
+* Issue Stage: New ideas are introduced, needs are identified, and the feasibility of changes is discussed.  
+* Pull Request Stage: Ideas from the Issue Stage are developed, tested, and approved for adoption.
+
+<img class="center" width="100%" height="100%" src="../../../../assets/governance-process-overview.png" alt="GTFS Governance Change Process overview"> 
+
+The issue stage is the same for all 3 tracks. The Pull Request stage differs in each of the 3 tracks. 
+
+## Stage 1: Issue 
+
+The Issue Stage is meant for discussing new ideas, identifying needs, and proposing improvements to the specification. Issues help evaluate the necessity and support for a change, while organizing the resources required to proceed to the Pull Request Stage. 
+
+It’s recommended to start at the Issue stage to build consensus around new ideas. However, if the proposal’s scope is already well-defined, beginning directly at the Pull Request stage is appropriate.
+
+## Stage 2: Pull Request 
+
+The Pull Request Stage is where ideas from the Issue Stage are developed and implemented into the specification. This stage is divided into 3 tracks depending on the change type. 
+
+The entire process happens within the [GitHub google/transit repository](https://github.com/google/transit/pulls) and ensures that all changes are thoroughly evaluated before being adopted.
+
+### Track A: Functional Changes
+
+<img class="center" width="100%" height="100%" src="../../../../assets/governance-process-functional.png" alt="GTFS Governance Change Process Track A"> 
+
+This process guides how the community proposes, reviews, and adopts Functional changes to the specification in the [GTFS Repository](https://github.com/google/transit/pulls). 
+
+* A proposal is submitted by opening a Pull Request in the GTFS Repository.   
+* The community engages in discussions to refine the proposal and reviews it before testing.   
+* After a preliminary vote, First Adopters test the proposed changes.   
+* The community votes to decide whether the changes should be officially adopted.  
+* Finally, changes are implemented into the specification.
+
+### Track B: Non-Functional Changes
+
+<img class="center" width="100%" height="100%" src="../../../../assets/governance-process-non-functional.png" alt="GTFS Governance Change Process Track B"> 
+
+This process guides how the community proposes, reviews, and adopts Non-Functional changes to the specification in the [GTFS Repository](https://github.com/google/transit/pulls).
+
+* A proposal is submitted by opening a Pull Request in the GTFS Repository.   
+* The community engages in discussions to refine the proposal.  
+* The community votes to decide whether the changes should be officially adopted.  
+* Finally, changes are implemented into the specification.
+
+### Track C: Documentation Maintenance
+
+<img class="center" width="100%" height="100%" src="../../../../assets/governance-process-documentation.png" alt="GTFS Governance Change Process Track C"> 
+
+This process guides how the community proposes, reviews, and adopts changes to maintain the documentation in the [GTFS Repository](https://github.com/google/transit/pulls).
+
+* A proposal is submitted by opening a Pull Request in the GTFS Repository.   
+* The community engages in discussions to refine the proposal  
+* Finally, changes are implemented into the specification.
+
+### Pull Request Stage Steps
+
+All of the steps in the Pull Request Stage are highlighted below. Consider that only Track A: Functional changes utilizes all the steps. Track B: Non-Functional changes and Track C: Documentation Maintenance utilize a shortened version of the process: 
+
+* Track A: Functional Changes utilizes steps:  
+    * 2.1 Pull Request Publication  
+    * 2.2 Pull Request Discussion  
+    * 2.3 Pull Request Review  
+    * 2.4 Vote to test  
+    * 2.5 Testing  
+    * 2.6 Vote to Adopt  
+    * 2.7 Adoption  
+* Track B: Non-Functional Changes utilizes steps:  
+    * 2.1 Pull Request Publication  
+    * 2.2 Pull Request Discussion  
+    * 2.3 Pull Request Review  
+    * 2.6 Vote to Adopt  
+    * 2.7 Adoption  
+* Track C: Documentation Maintenance utilizes steps:   
+    * 2.1 Pull Request Publication  
+    * 2.2 Pull Request Discussion  
+    * 2.3 Pull Request Review  
+    * 2.7 Adoption
diff --git a/docs/en/community/governance/schedule/test-process-steps.md b/docs/en/community/governance/schedule/test-process-steps.md
