From ffa6e10c448771914b018b6840b6061d631c2777 Mon Sep 17 00:00:00 2001 From: Thomas Gran Date: Fri, 15 Sep 2023 15:53:41 +0200 Subject: [PATCH 01/21] doc: Architectural Decision Records --- .../workflows/close_stale_pr_and_issues.yml | 4 +- ADRs.md | 94 +++++++++++++++++++ ARCHITECTURE.md | 6 +- CODE_CONVENTIONS.md | 25 ++--- ISSUE_TEMPLATE/ADR.md | 32 +++++++ .../ISSUE_TEMPLATE.md | 0 .../transit/service/StopModel.java | 2 + 7 files changed, 145 insertions(+), 18 deletions(-) create mode 100644 ADRs.md create mode 100644 ISSUE_TEMPLATE/ADR.md rename ISSUE_TEMPLATE => ISSUE_TEMPLATE/ISSUE_TEMPLATE.md (100%) diff --git a/.github/workflows/close_stale_pr_and_issues.yml b/.github/workflows/close_stale_pr_and_issues.yml index 98619f7e763..0c337fbc485 100644 --- a/.github/workflows/close_stale_pr_and_issues.yml +++ b/.github/workflows/close_stale_pr_and_issues.yml @@ -20,5 +20,7 @@ jobs: days-before-stale: 90 days-before-close: 30 operations-per-run: 260 - exempt-issue-labels: 'Roadmap' + exempt-issue-labels: + - 'Roadmap' + - 'ADR' ascending: true diff --git a/ADRs.md b/ADRs.md new file mode 100644 index 00000000000..27fa73faf8c --- /dev/null +++ b/ADRs.md @@ -0,0 +1,94 @@ +# Architectural Decision Records (ADRs) + +An Architectural Decision (AD) is a justified software design choice that addresses a functional or +non-functional requirement that is architecturally significant. ([adr.github.io](https://adr.github.io/)) + +## Process + +Architectural decisions we make in the developer meetings are recorded here. If the decision is +small and uncontroversial, but yet important and can be expressed in maximum 2 sentences, we will +list it here without any reference. If the decision require a bit more discussion and explanations +an issue on GitHub should be created - use the template below. + +### How to discuss and document an Architectural Decision + + - [Create a new issue](https://github.com/opentripplanner/OpenTripPlanner/issues/new/choose?template=adr.md) +using the [ADR.md](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/ISSUE_TEMPLATE/ADR.md) +template. + - Make sure to update the main description based on the feedback/discussion and decisions in the + developer meeting. + - The final approval is done in the developer meeting, at least 3 developers representing 3 + different organisations should approve - and no vote against the proposal. If the developers + are not able to agree the PLC can decide. + - Add the ADR to the list below. Maximum two sentences should be used - try to keep it as short as + possible. Remember to link to the discussion. + - References to Architectural Decision Records in reviews can be done by linking or just typing + e.g. `ADR2`. Use the `[ADR1]()` + + +## Records + +### ADR-0 Scout rule +Leave Things BETTER than you found them - clean up code you visit or/and add unit +tests. Expect to include some code cleanup as part of all PRs. + +### ADR-1 Naming +[Follow naming conventions](CODE_CONVENTIONS.md#naming-conventions) . Make sure the +code is easy to read and understand. + +### ADR-2 Code documentation - JavaDoc +Document the business intention and decisions in the relevant code. Do not repeat the logic +expressed in the code. The prefered way is to use JavaDoc, you may have to refactor part of your +code to encapsulate the business logic into a method or class to do this. + +> If you decide to NOT follow an Architectural Decision, then expect to document why. + +**See also** + - [Developers-Guide > Code comments](docs/Developers-Guide.md#code-comments). + - [Codestyle > Javadoc Guidlines](docs/Codestyle.md#javadoc-guidlines) - JavaDoc checklist + +### ADR-3 Code style +OTP uses prettier to format code. For more information on code style see the +[Codestyle](docs/Codestyle.md) document. + +### ADR-4 OOP +Respect Object-Oriented principals + - Honer encapsulation & Single-responsibility principle + - Abstraction - Use interfaces when a module need "someone" to play a role + - Inheritance - Inheritances expresses “is-a” and/or “has-a” relationship, do not use it "just" + to share data/functionality. + - Use polymorphism and not `instanceof`. + +### ADR-5 Dependency injection +Use dependency injection to wire components. You can use manual DI or Dagger. Put the +wiring code in `/configure/Module.java`. + +### ADR-6 Module encapsulation +Keep modules clean. Consider adding an `api`, `spi` and mapping code to +isolate the module from the rest of the code. Avoid circular dependencies between modules. + +### ADR-7 JavaDoc +Document all `public` types, methods and fields. + +### ADR-8 API doc +Document API and configuration parameters. + +### ADR-9 DRY +Keep the code [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) - Do not +repeat yourself. Avoid implementing the same business rule in two places -> refactor. + +### ADR-10 Feature envy +[Feature envy](https://refactoring.guru/smells/feature-envy) + +### ADR-11 Test coverage +All business logic should have unit tests. Keep integration/system tests to a +minimum. Add test at the lowest level practical to test the business feature. Prefer unit tests on +a method over a class, over a module, over the system. + +### ADR-12 Immutable types +Prefer immutable types over mutable. Use builders where appropriate. See +[Records, POJOs and Builders](CODE_CONVENTIONS.md#records-pojos-and-builders) + +### ADR-13 Records +[Avoid using records if you can not encapsulate it properly](CODE_CONVENTIONS.md#records) + diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index dd0f986e518..7233bf9d0b3 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,6 +1,6 @@ # OTP Architecture -OTP is developed over more than 10 years, and most of the design documentation is in the code as +OTP is developed over more than 15 years, and most of the design documentation is in the code as comments and JavaDoc. Over the years the complexity have increased, and the natural developer turnover creates a demand for more architecture and design documentation. The new OTP2 documentation is put together with the source; hopefully making it easier to maintain. Instead of documenting @@ -11,6 +11,10 @@ This document is far from complete - hopefully it can evolve over time and becom introduction to OTP architecture. The OTP project GitHub issues are a good place to look for detailed discussions on many design decisions. +We document Architectural Decision in a log. Make sure you as a developer is familiar with the +decisions and follow them. Reviewers should use them actively when reviewing code and may use them +to ask for changes. + Be sure to also read the [developer documentation](docs/Developers-Guide.md). ## Modules/Components diff --git a/CODE_CONVENTIONS.md b/CODE_CONVENTIONS.md index a9fd73a0497..9a53e32fcc1 100644 --- a/CODE_CONVENTIONS.md +++ b/CODE_CONVENTIONS.md @@ -12,21 +12,6 @@ These conventions are not "hard" rules, and often there might be other forces wh decision in another direction, in that case documenting your choice is often enough to pass the review. -## Best practices - in focus - -- [ ] Document `public` interfaces, classes and methods - especially those part of a module api. -- [ ] Leave Things BETTER than you found them - clean up code you visit or/and add unit tests. -- [ ] [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) - Do not repeat yourself. Avoid implementing the same business rule in two places -> refactor. -- [ ] [Feature envy](https://refactoring.guru/smells/feature-envy) -- [ ] Make types immutable if possible. References to other Entities might need to be mutable, if - so try to init them once, and throw an exception if set again. - Example: - -```java -Builder initStop(Stop stop) { - this.stop = requireNotInitialized(this.stop, stop); -} -``` ## Naming Conventions @@ -104,7 +89,15 @@ stop = stop.copyOf().withPrivateCode("TEX").build(); ## Records, POJOs and Builders We prefer immutable typesafe types over flexibility and "short" class definitions. This make -the code more robust and less error-prune. +the code more robust and less error-prune. References to other entities might need to be mutable, +if so try to init them once, and throw an exception if set again. Example: + +```java +Builder initStop(Stop stop) { + this.stop = requireNotInitialized(this.stop, stop); +} +``` + ### Records diff --git a/ISSUE_TEMPLATE/ADR.md b/ISSUE_TEMPLATE/ADR.md new file mode 100644 index 00000000000..d0d04cc9cf8 --- /dev/null +++ b/ISSUE_TEMPLATE/ADR.md @@ -0,0 +1,32 @@ + + +### Description +*One or two sentences witch goes into the [Architectural Decision Records](../ADRs.md) document +later* + +### Context and Problem Statement +*Describe the context and problem statement, e.g., in free form using two to three sentences. You +may want to articulate the issue in form of a question* + +### Other options + + - + +### Decision & Consequences +Describes the effects of the change. What becomes easier? What will be more difficult? + +#### Positive Consequences + + - + +#### Negative Consequences + + - + +#### Checklist +- [ ] Tag issue with `ADR`. +- [ ] Give it a meaningful title that quickly lets the reader understand what this ADR is all about. +- [ ] Approved in a developer meeting with 3 votes in favor (3 organisations) +- [ ] This issue description is up-to-date with the discussion below. +- [ ] The name and description is added to the + [Architectural Decision Records](../ADRs.md) document and the ADR is linked this issue. diff --git a/ISSUE_TEMPLATE b/ISSUE_TEMPLATE/ISSUE_TEMPLATE.md similarity index 100% rename from ISSUE_TEMPLATE rename to ISSUE_TEMPLATE/ISSUE_TEMPLATE.md diff --git a/src/main/java/org/opentripplanner/transit/service/StopModel.java b/src/main/java/org/opentripplanner/transit/service/StopModel.java index 110260c1cde..ee90bd0ce71 100644 --- a/src/main/java/org/opentripplanner/transit/service/StopModel.java +++ b/src/main/java/org/opentripplanner/transit/service/StopModel.java @@ -23,6 +23,8 @@ /** * Repository for Stop entities. + * + * ARCHITECTURAL_DECISION_RECORDS.md */ public class StopModel implements Serializable { From 37ac87da3eb78ed2580873b749777c364b725409 Mon Sep 17 00:00:00 2001 From: Thomas Gran Date: Thu, 5 Oct 2023 18:18:40 +0200 Subject: [PATCH 02/21] Apply suggestions from code review Co-authored-by: Leonard Ehrenfried --- ADRs.md | 2 +- CODE_CONVENTIONS.md | 2 +- ISSUE_TEMPLATE/ADR.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/ADRs.md b/ADRs.md index 27fa73faf8c..b13054aff0e 100644 --- a/ADRs.md +++ b/ADRs.md @@ -53,7 +53,7 @@ OTP uses prettier to format code. For more information on code style see the ### ADR-4 OOP Respect Object-Oriented principals - - Honer encapsulation & Single-responsibility principle + - Honor encapsulation & Single-responsibility principle - Abstraction - Use interfaces when a module need "someone" to play a role - Inheritance - Inheritances expresses “is-a” and/or “has-a” relationship, do not use it "just" to share data/functionality. diff --git a/CODE_CONVENTIONS.md b/CODE_CONVENTIONS.md index 9a53e32fcc1..093c2afdcb5 100644 --- a/CODE_CONVENTIONS.md +++ b/CODE_CONVENTIONS.md @@ -89,7 +89,7 @@ stop = stop.copyOf().withPrivateCode("TEX").build(); ## Records, POJOs and Builders We prefer immutable typesafe types over flexibility and "short" class definitions. This make -the code more robust and less error-prune. References to other entities might need to be mutable, +the code more robust and less error-prone. References to other entities might need to be mutable, if so try to init them once, and throw an exception if set again. Example: ```java diff --git a/ISSUE_TEMPLATE/ADR.md b/ISSUE_TEMPLATE/ADR.md index d0d04cc9cf8..9e32a45204b 100644 --- a/ISSUE_TEMPLATE/ADR.md +++ b/ISSUE_TEMPLATE/ADR.md @@ -1,7 +1,7 @@ ### Description -*One or two sentences witch goes into the [Architectural Decision Records](../ADRs.md) document +*One or two sentences which goes into the [Architectural Decision Records](../ADRs.md) document later* ### Context and Problem Statement From 247ec7d629ffb7b1293a4887a23895d1708fa305 Mon Sep 17 00:00:00 2001 From: Andrew Byrd Date: Thu, 25 Jan 2024 20:19:19 +0800 Subject: [PATCH 03/21] Rewording in ARCHITECTURE.md Co-authored-by: Jim Martens --- ARCHITECTURE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 7233bf9d0b3..ece6cf811dd 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,6 +1,6 @@ # OTP Architecture -OTP is developed over more than 15 years, and most of the design documentation is in the code as +OTP has been developed for more than 15 years, and most of the design documentation is in the code as comments and JavaDoc. Over the years the complexity have increased, and the natural developer turnover creates a demand for more architecture and design documentation. The new OTP2 documentation is put together with the source; hopefully making it easier to maintain. Instead of documenting From 254657f4b478d7fdc8a3e06908fba4d5b1523b3a Mon Sep 17 00:00:00 2001 From: Andrew Byrd Date: Thu, 25 Jan 2024 20:50:06 +0800 Subject: [PATCH 04/21] add ADR for dependency injection --- ADRs.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/ADRs.md b/ADRs.md index b13054aff0e..3bcd7213e91 100644 --- a/ADRs.md +++ b/ADRs.md @@ -92,3 +92,10 @@ Prefer immutable types over mutable. Use builders where appropriate. See ### ADR-13 Records [Avoid using records if you can not encapsulate it properly](CODE_CONVENTIONS.md#records) +### ADR-14 Dependency Injection +OTP will use a dependency injection library or framework to handle object lifecycles (particularly +request-scoped vs. singleton scoped) and ensure selective availability of components, services, +context, and configuration at their site of use. Systems that operate via imperative Java code +(whether hand-written or generated) will be preferred over those operating through reflection or +external markup files. See [additional background](https://github.com/opentripplanner/OpenTripPlanner/pull/5360#issuecomment-1910134299). + From 868582b012da39842afe212bcee87e9e4b16b097 Mon Sep 17 00:00:00 2001 From: Leonard Ehrenfried Date: Tue, 2 Jul 2024 17:27:37 +0200 Subject: [PATCH 05/21] Small stylistic changes --- ISSUE_TEMPLATE/ADR.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/ISSUE_TEMPLATE/ADR.md b/ISSUE_TEMPLATE/ADR.md index 9e32a45204b..695c75925a5 100644 --- a/ISSUE_TEMPLATE/ADR.md +++ b/ISSUE_TEMPLATE/ADR.md @@ -1,7 +1,7 @@ ### Description -*One or two sentences which goes into the [Architectural Decision Records](../ADRs.md) document +*One or two sentences which go into the [Architectural Decision Records](../ADRs.md) document later* ### Context and Problem Statement @@ -26,7 +26,7 @@ Describes the effects of the change. What becomes easier? What will be more diff #### Checklist - [ ] Tag issue with `ADR`. - [ ] Give it a meaningful title that quickly lets the reader understand what this ADR is all about. -- [ ] Approved in a developer meeting with 3 votes in favor (3 organisations) -- [ ] This issue description is up-to-date with the discussion below. -- [ ] The name and description is added to the +- [ ] Get it approved in a developer meeting with 3 votes in favor (3 organisations). +- [ ] Update the issue description is up-to-date with the discussion below. +- [ ] Add name and description to the [Architectural Decision Records](../ADRs.md) document and the ADR is linked this issue. From 4253f3239bdddcebb53af92b4f8669890d5bd421 Mon Sep 17 00:00:00 2001 From: Thomas Gran Date: Wed, 3 Jul 2024 11:58:59 +0200 Subject: [PATCH 06/21] Revert changes made to StopModel --- .../java/org/opentripplanner/transit/service/StopModel.java | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/main/java/org/opentripplanner/transit/service/StopModel.java b/src/main/java/org/opentripplanner/transit/service/StopModel.java index ee90bd0ce71..110260c1cde 100644 --- a/src/main/java/org/opentripplanner/transit/service/StopModel.java +++ b/src/main/java/org/opentripplanner/transit/service/StopModel.java @@ -23,8 +23,6 @@ /** * Repository for Stop entities. - * - * ARCHITECTURAL_DECISION_RECORDS.md */ public class StopModel implements Serializable { From c1bcfddc7e6e0489ff754b93f61eab6f08fbb725 Mon Sep 17 00:00:00 2001 From: Thomas Gran Date: Wed, 3 Jul 2024 12:38:25 +0200 Subject: [PATCH 07/21] doc: Update ADR-11 --- ADRs.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/ADRs.md b/ADRs.md index 3bcd7213e91..5fa3ad2d923 100644 --- a/ADRs.md +++ b/ADRs.md @@ -81,9 +81,11 @@ repeat yourself. Avoid implementing the same business rule in two places -> refa [Feature envy](https://refactoring.guru/smells/feature-envy) ### ADR-11 Test coverage -All business logic should have unit tests. Keep integration/system tests to a -minimum. Add test at the lowest level practical to test the business feature. Prefer unit tests on -a method over a class, over a module, over the system. +All _business_ logic should have unit tests. Keep integration/system tests to a minimum. Add test at +the lowest level practical to test the business feature. Prefer unit tests on a method over a class, +over a module, over the system. On all non-trivial code full _branch_ test coverage is preferable. +Tests should be designed to genuinely demonstrate correctness or adherence to specifications, not +simply inflate line coverage numbers. ### ADR-12 Immutable types Prefer immutable types over mutable. Use builders where appropriate. See From 6b8da31fd361b38e06bba5eb20ec97dd27ac83e9 Mon Sep 17 00:00:00 2001 From: Thomas Gran Date: Wed, 3 Jul 2024 13:01:06 +0200 Subject: [PATCH 08/21] doc: Add link to ADR.md in ARCHITECTURE.md --- ARCHITECTURE.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index ece6cf811dd..ff12aee97d0 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -11,9 +11,9 @@ This document is far from complete - hopefully it can evolve over time and becom introduction to OTP architecture. The OTP project GitHub issues are a good place to look for detailed discussions on many design decisions. -We document Architectural Decision in a log. Make sure you as a developer is familiar with the -decisions and follow them. Reviewers should use them actively when reviewing code and may use them -to ask for changes. +We document [Architectural Decision](ADRs.md) in a log. Make sure you as a developer are familiar +with the decisions and follow them. Reviewers should use them actively when reviewing code and may +use them to ask for changes. Be sure to also read the [developer documentation](docs/Developers-Guide.md). From 5a0da59e2be315d5682eb04b91176e1a45aac2da Mon Sep 17 00:00:00 2001 From: Thomas Gran Date: Wed, 3 Jul 2024 13:13:39 +0200 Subject: [PATCH 09/21] doc: Title Case --- ADRs.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/ADRs.md b/ADRs.md index 5fa3ad2d923..757891f3b8e 100644 --- a/ADRs.md +++ b/ADRs.md @@ -36,7 +36,7 @@ tests. Expect to include some code cleanup as part of all PRs. [Follow naming conventions](CODE_CONVENTIONS.md#naming-conventions) . Make sure the code is easy to read and understand. -### ADR-2 Code documentation - JavaDoc +### ADR-2 Code Documentation - JavaDoc Document the business intention and decisions in the relevant code. Do not repeat the logic expressed in the code. The prefered way is to use JavaDoc, you may have to refactor part of your code to encapsulate the business logic into a method or class to do this. @@ -59,11 +59,11 @@ Respect Object-Oriented principals to share data/functionality. - Use polymorphism and not `instanceof`. -### ADR-5 Dependency injection +### ADR-5 Dependency Injection Use dependency injection to wire components. You can use manual DI or Dagger. Put the wiring code in `/configure/Module.java`. -### ADR-6 Module encapsulation +### ADR-6 Module Encapsulation Keep modules clean. Consider adding an `api`, `spi` and mapping code to isolate the module from the rest of the code. Avoid circular dependencies between modules. @@ -77,17 +77,17 @@ Document API and configuration parameters. Keep the code [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) - Do not repeat yourself. Avoid implementing the same business rule in two places -> refactor. -### ADR-10 Feature envy +### ADR-10 Avoid Feature Envy [Feature envy](https://refactoring.guru/smells/feature-envy) -### ADR-11 Test coverage +### ADR-11 Test Coverage All _business_ logic should have unit tests. Keep integration/system tests to a minimum. Add test at the lowest level practical to test the business feature. Prefer unit tests on a method over a class, over a module, over the system. On all non-trivial code full _branch_ test coverage is preferable. Tests should be designed to genuinely demonstrate correctness or adherence to specifications, not simply inflate line coverage numbers. -### ADR-12 Immutable types +### ADR-12 Immutable Types Prefer immutable types over mutable. Use builders where appropriate. See [Records, POJOs and Builders](CODE_CONVENTIONS.md#records-pojos-and-builders) From 27eb36ca5518866c71f1656bcf334f5c22a3f8a4 Mon Sep 17 00:00:00 2001 From: Thomas Gran Date: Fri, 5 Jul 2024 15:46:23 +0200 Subject: [PATCH 10/21] Cleanup decision records based on reviews. --- ADRs.md | 103 ------------ ARCHITECTURE.md | 6 +- DECISION_RECORDS.md | 106 +++++++++++++ ISSUE_TEMPLATE/ADR.md | 32 ---- .../dev/decisionrecords}/Codestyle.md | 2 +- .../dev/decisionrecords/NamingConventions.md | 148 +----------------- .../decisionrecords/RecordsPOJOsBuilders.md | 112 +++++++++++++ doc/dev/decisionrecords/UseDecisionRecords.md | 37 +++++ doc/dev/decisionrecords/_TEMPLATE.md | 31 ++++ docs/Developers-Guide.md | 2 +- 10 files changed, 299 insertions(+), 280 deletions(-) delete mode 100644 ADRs.md create mode 100644 DECISION_RECORDS.md delete mode 100644 ISSUE_TEMPLATE/ADR.md rename {docs => doc/dev/decisionrecords}/Codestyle.md (98%) rename CODE_CONVENTIONS.md => doc/dev/decisionrecords/NamingConventions.md (57%) create mode 100644 doc/dev/decisionrecords/RecordsPOJOsBuilders.md create mode 100644 doc/dev/decisionrecords/UseDecisionRecords.md create mode 100644 doc/dev/decisionrecords/_TEMPLATE.md diff --git a/ADRs.md b/ADRs.md deleted file mode 100644 index 757891f3b8e..00000000000 --- a/ADRs.md +++ /dev/null @@ -1,103 +0,0 @@ -# Architectural Decision Records (ADRs) - -An Architectural Decision (AD) is a justified software design choice that addresses a functional or -non-functional requirement that is architecturally significant. ([adr.github.io](https://adr.github.io/)) - -## Process - -Architectural decisions we make in the developer meetings are recorded here. If the decision is -small and uncontroversial, but yet important and can be expressed in maximum 2 sentences, we will -list it here without any reference. If the decision require a bit more discussion and explanations -an issue on GitHub should be created - use the template below. - -### How to discuss and document an Architectural Decision - - - [Create a new issue](https://github.com/opentripplanner/OpenTripPlanner/issues/new/choose?template=adr.md) -using the [ADR.md](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/ISSUE_TEMPLATE/ADR.md) -template. - - Make sure to update the main description based on the feedback/discussion and decisions in the - developer meeting. - - The final approval is done in the developer meeting, at least 3 developers representing 3 - different organisations should approve - and no vote against the proposal. If the developers - are not able to agree the PLC can decide. - - Add the ADR to the list below. Maximum two sentences should be used - try to keep it as short as - possible. Remember to link to the discussion. - - References to Architectural Decision Records in reviews can be done by linking or just typing - e.g. `ADR2`. Use the `[ADR1]()` - - -## Records - -### ADR-0 Scout rule -Leave Things BETTER than you found them - clean up code you visit or/and add unit -tests. Expect to include some code cleanup as part of all PRs. - -### ADR-1 Naming -[Follow naming conventions](CODE_CONVENTIONS.md#naming-conventions) . Make sure the -code is easy to read and understand. - -### ADR-2 Code Documentation - JavaDoc -Document the business intention and decisions in the relevant code. Do not repeat the logic -expressed in the code. The prefered way is to use JavaDoc, you may have to refactor part of your -code to encapsulate the business logic into a method or class to do this. - -> If you decide to NOT follow an Architectural Decision, then expect to document why. - -**See also** - - [Developers-Guide > Code comments](docs/Developers-Guide.md#code-comments). - - [Codestyle > Javadoc Guidlines](docs/Codestyle.md#javadoc-guidlines) - JavaDoc checklist - -### ADR-3 Code style -OTP uses prettier to format code. For more information on code style see the -[Codestyle](docs/Codestyle.md) document. - -### ADR-4 OOP -Respect Object-Oriented principals - - Honor encapsulation & Single-responsibility principle - - Abstraction - Use interfaces when a module need "someone" to play a role - - Inheritance - Inheritances expresses “is-a” and/or “has-a” relationship, do not use it "just" - to share data/functionality. - - Use polymorphism and not `instanceof`. - -### ADR-5 Dependency Injection -Use dependency injection to wire components. You can use manual DI or Dagger. Put the -wiring code in `/configure/Module.java`. - -### ADR-6 Module Encapsulation -Keep modules clean. Consider adding an `api`, `spi` and mapping code to -isolate the module from the rest of the code. Avoid circular dependencies between modules. - -### ADR-7 JavaDoc -Document all `public` types, methods and fields. - -### ADR-8 API doc -Document API and configuration parameters. - -### ADR-9 DRY -Keep the code [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) - Do not -repeat yourself. Avoid implementing the same business rule in two places -> refactor. - -### ADR-10 Avoid Feature Envy -[Feature envy](https://refactoring.guru/smells/feature-envy) - -### ADR-11 Test Coverage -All _business_ logic should have unit tests. Keep integration/system tests to a minimum. Add test at -the lowest level practical to test the business feature. Prefer unit tests on a method over a class, -over a module, over the system. On all non-trivial code full _branch_ test coverage is preferable. -Tests should be designed to genuinely demonstrate correctness or adherence to specifications, not -simply inflate line coverage numbers. - -### ADR-12 Immutable Types -Prefer immutable types over mutable. Use builders where appropriate. See -[Records, POJOs and Builders](CODE_CONVENTIONS.md#records-pojos-and-builders) - -### ADR-13 Records -[Avoid using records if you can not encapsulate it properly](CODE_CONVENTIONS.md#records) - -### ADR-14 Dependency Injection -OTP will use a dependency injection library or framework to handle object lifecycles (particularly -request-scoped vs. singleton scoped) and ensure selective availability of components, services, -context, and configuration at their site of use. Systems that operate via imperative Java code -(whether hand-written or generated) will be preferred over those operating through reflection or -external markup files. See [additional background](https://github.com/opentripplanner/OpenTripPlanner/pull/5360#issuecomment-1910134299). - diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index ff12aee97d0..d73b09edc31 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -7,11 +7,11 @@ is put together with the source; hopefully making it easier to maintain. Instead modules in old style _package-info.java_ files we use _package.md_ files. This document should serve as an index to all existing top-level documented components. -This document is far from complete - hopefully it can evolve over time and become a good +This document is far from complete. Hopefully it can evolve over time and become a good introduction to OTP architecture. The OTP project GitHub issues are a good place to look for detailed discussions on many design decisions. -We document [Architectural Decision](ADRs.md) in a log. Make sure you as a developer are familiar +We document [Decision Records](DECISION_RECORDS.md) in a log. Make sure you as a developer are familiar with the decisions and follow them. Reviewers should use them actively when reviewing code and may use them to ask for changes. @@ -30,7 +30,7 @@ examples. The Transit model is more complex than the VehiclePosition model. class has the same name as the interface with prefix `Default`. - `Domain Model` A model witch encapsulate a business area. In the drawing two examples are shown, the `transit` and `vhicleposition` domain model. The transit model is more complex so the - implementation have a separate `Service` and `Repository`. Almost all http endpoints are , + implementation has a separate `Service` and `Repository`. Almost all http endpoints are, read-only so the `Service` can focus on serving the http API endpoints, while the repository is used to maintain the model by the updaters. diff --git a/DECISION_RECORDS.md b/DECISION_RECORDS.md new file mode 100644 index 00000000000..dbe044c6168 --- /dev/null +++ b/DECISION_RECORDS.md @@ -0,0 +1,106 @@ +# Records + + +## Use-Decision-Records + +We will [use decision-records](doc/dev/decisionrecords/UseDecisionRecords.md) to document OTP +development relevant decision. Use the [template](doc/dev/decisionrecords/_TEMPLATE.md) to describe +new decision records. + + +## Scout-Rule + +Leave things BETTER than you found them, clean up code you visit or/and add unit +tests. Expect to include some code cleanup as part of all PRs. + +## Follow-Naming-Conventions + +Use established terminology from GTFS, NeTEx or the existing OTP code. Make sure the code is easy +to read and understand. [Follow naming conventions](CODE_CONVENTIONS.md#naming-conventions) . + + +## Write-Code-Documentation - Use JavaDoc + +Document the business intention and decisions in the relevant code. Do not repeat the logic +expressed in the code. Use JavaDoc, you may have to refactor part of your code to encapsulate the +business logic into a method or class to do this. + +Document all `public` types, methods and fields with JavaDoc. It is ok to document implementation +notes on `private` members and as inline comments. + +> If you decide to NOT follow these decision records, then you must document why. + +**See also** + - [Developers-Guide > Code comments](docs/Developers-Guide.md#code-comments). + - [Codestyle > Javadoc Guidlines](doc/dev/decisionrecords/Codestyle.md#javadoc-guidlines) - JavaDoc checklist + + +## Document-Config-and-APIs + +Document API and configuration parameters. + + +## Respect-Codestyle + +OTP uses prettier to format code. For more information on code style see the +[Codestyle](doc/dev/decisionrecords/Codestyle.md) document. + + +## Use-Object-Oriented-Principals + +Respect Object-Oriented principals + - Honor encapsulation & Single-responsibility principle + - Abstraction - Use interfaces when a module needs "someone" to play a role + - Inheritance - Inheritances expresses “is-a” and/or “has-a” relationship, do not use it "just" + to share data/functionality. + - Use polymorphism and not `instanceof`. + + +## Use-Dependency-Injection + +Use dependency injection to wire components. You can use manual DI or Dagger. Put the +wiring code in `/configure/Module.java`. + +OTP will use a dependency injection library or framework to handle object lifecycles (particularly +request-scoped vs. singleton scoped) and ensure selective availability of components, services, +context, and configuration at their site of use. Systems that operate via imperative Java code +(whether hand-written or generated) will be preferred over those operating through reflection or +external markup files. See [additional background](https://github.com/opentripplanner/OpenTripPlanner/pull/5360#issuecomment-1910134299). + +## Use-Module-Encapsulation + +Keep modules clean. Consider adding an `api`, `spi` and mapping code to +isolate the module from the rest of the code. Avoid circular dependencies between modules. + + +## DRY - Do not repeat yourself + +Keep the code [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) - Do not +repeat yourself. Avoid implementing the same business rule in two places -> refactor. + + +## Avoid-Feature-Envy + +[Feature envy](https://refactoring.guru/smells/feature-envy) + + +## Test-Coverage + +All _business_ logic should have unit tests. Keep integration/system tests to a minimum. Add test at +the lowest level practical to test the business feature. Prefer unit tests on a method over a class, +over a module, over the system. On all non-trivial code, full _branch_ test coverage is preferable. +Tests should be designed to genuinely demonstrate correctness or adherence to specifications, not +simply inflate line coverage numbers. + + +## Use-Immutable-Types + +Prefer immutable types over mutable. Use builders where appropriate. See +[Records, POJOs and Builders](doc/dev/decisionrecords/RecordsPOJOsBuilders.md#records-pojos-and-builders) + + +## Be-Careful-With-Records + +[Avoid using records if you cannot encapsulate it properly](doc/dev/decisionrecords/RecordsPOJOsBuilders.md#records) + + diff --git a/ISSUE_TEMPLATE/ADR.md b/ISSUE_TEMPLATE/ADR.md deleted file mode 100644 index 695c75925a5..00000000000 --- a/ISSUE_TEMPLATE/ADR.md +++ /dev/null @@ -1,32 +0,0 @@ - - -### Description -*One or two sentences which go into the [Architectural Decision Records](../ADRs.md) document -later* - -### Context and Problem Statement -*Describe the context and problem statement, e.g., in free form using two to three sentences. You -may want to articulate the issue in form of a question* - -### Other options - - - - -### Decision & Consequences -Describes the effects of the change. What becomes easier? What will be more difficult? - -#### Positive Consequences - - - - -#### Negative Consequences - - - - -#### Checklist -- [ ] Tag issue with `ADR`. -- [ ] Give it a meaningful title that quickly lets the reader understand what this ADR is all about. -- [ ] Get it approved in a developer meeting with 3 votes in favor (3 organisations). -- [ ] Update the issue description is up-to-date with the discussion below. -- [ ] Add name and description to the - [Architectural Decision Records](../ADRs.md) document and the ADR is linked this issue. diff --git a/docs/Codestyle.md b/doc/dev/decisionrecords/Codestyle.md similarity index 98% rename from docs/Codestyle.md rename to doc/dev/decisionrecords/Codestyle.md index d127ff21e5c..f5b10d669c7 100644 --- a/docs/Codestyle.md +++ b/doc/dev/decisionrecords/Codestyle.md @@ -51,7 +51,7 @@ Editor > Code Style_. Then select **Project** in the \_Scheme drop down. You can run the Prettier Maven plugin as an external tool in IntelliJ. Set it up as an `External tool` and assign a key-shortcut to the tool execution. -![External Tool Dialog](images/ExternalToolDialog.png) +![External Tool Dialog](../../../docs/images/ExternalToolDialog.png) ``` Name: Prettier Format Current File diff --git a/CODE_CONVENTIONS.md b/doc/dev/decisionrecords/NamingConventions.md similarity index 57% rename from CODE_CONVENTIONS.md rename to doc/dev/decisionrecords/NamingConventions.md index 093c2afdcb5..97d89404942 100644 --- a/CODE_CONVENTIONS.md +++ b/doc/dev/decisionrecords/NamingConventions.md @@ -1,21 +1,6 @@ -# Code Conventions +# Naming Conventions -We try to follow these conventions or best practices. The goal is to get cleaner code and make the -review process easier: - -- the developer knows what to expect -- the reviewer knows what to look for -- discussions and personal preferences can be avoided saving time -- new topics should be documented here - -These conventions are not "hard" rules, and often there might be other forces which pull a -decision in another direction, in that case documenting your choice is often enough to pass the -review. - - -## Naming Conventions - -### Packages +## Packages Try to arrange code by domain functionality, not technology. The main structure of a package should be `org.opentripplanner...`. @@ -34,14 +19,14 @@ be `org.opentripplanner...`. | `util` | General "util" functionality, often characterized by `static` methods. Dependencies to other OTP packages is NOT allowed, only 3rd party utils libs. | | `o.o.apis` | OTP external endpoints. Note! Many apis are in the Sandbox where they are in the `o.o.ext` package. | -> **Note!** The above is the goal, the current package structure needs cleanup. +> **Note!** The above is the goal, the current package structure needs cleanup. > **Note!** Util methods depending on an OTP type/component should go into that type/component, not in the -utils class. E.g. static factory methods. Warning the "pure" utilities right now are placed into +utils class. E.g. static factory methods. Warning the "pure" utilities right now are placed into sub-packages of `o.o.util`, the root package needs cleanup. -### Methods +## Methods Here are a list of common prefixes used, and what to expect. @@ -67,15 +52,15 @@ These prefixes are also "allowed", but not preferred - they have some kind of ne | `setStop(Stop stop)` | Set a mutable stop reference. Avoid if not part of natural lifecycle. Use `initStop(...)` if possible | | `getStop() : Stop` | Old style accessor, use the shorter form `stop() : Stop` | -### Service, Model and Repository +## Service, Model and Repository -![MainModelOverview](docs/images/ServiceModelOverview.png) +![MainModelOverview](docs/images/ServiceModelOverview.png) Naming convention for builders with and without a context. -##### Graph Build and tests run without a context +#### Graph Build and tests run without a context ```Java // Create a new Stop @@ -84,120 +69,3 @@ trip = Trip.of(id).withName("The Express").build(); // Modify and existing stop stop = stop.copyOf().withPrivateCode("TEX").build(); ``` - - -## Records, POJOs and Builders - -We prefer immutable typesafe types over flexibility and "short" class definitions. This make -the code more robust and less error-prone. References to other entities might need to be mutable, -if so try to init them once, and throw an exception if set again. Example: - -```java -Builder initStop(Stop stop) { - this.stop = requireNotInitialized(this.stop, stop); -} -``` - - -### Records - -You may use records, but avoid using records if you can not encapsulate it properly. Be especially -aware of arrays fields (can not be protected) and collections (remember to make a defensive copy). -If you need to override `equals` and `hashCode`, then it is probably not worth it. -Be aware that `equals` compare references, not the value of a field. Consider overriding `toString`. - -### Builders - -OTP used a simple builder pattern in many places, especially when creating immutable types. - -#### Builder conventions -- Use factory methods to create builder, either `of()` or `copyOf()`. The _copyOf_ uses an existing - instance as its base. The `of()` creates a builder with all default values set. All constructors - should be private (or package local) to enforce the use of the factory methods. -- If the class have more than 5 fields avoid using an inner class builder, instead create a builder - in the same package. -- Make all fields in the main class final to enforce immutability. -- Consider using utility methods for parameter checking, like `Objects#requireNonNull` and - `ObjectUtils.ifNotNull`. -- Validate all fields in the main type constructor(i.e. not in the builder), especially null checks. - Prefer default values over null-checks. All business logic using the type can rely on its validity. -- You may keep the original instance in the builder to avoid creating a new object if nothing - changed. This prevents polluting the heap for long-lived objects and make comparison very fast. -- There is no need to provide all get accessors in the Builder if not needed. -- Unit-test builders and verify all fields are copied over. -- For nested builders see the field `nested` in the example. - -
- Builder example - -```Java -/** - * THIS CLASS IS IMMUTABLE AND THREAD-SAFE - */ -public class A { - public static final A DEFAULT = new A(); - private final List names; - private final int age; - private final B nested; - - private A() { - this.names = List.of("default"); - this.age = 7; - this.nested = B.of(); - } - - private A(Builder builder) { - this.names = List.copyOf(builder.names); - this.age = builder.age; - this.nested = builder.nested(); - - if(age < 0 || age > 150) { - throw new IllegalArgumentException("Age is out of range[0..150]: " + age); - } - } - - public static A.Builder of() { return DEFAULT.copyOf(); } - public A.Builder copyOf() { return new Builder(this); } - - public List listNames() { return names; } - public int age() { return age; } - - public boolean equals(Object other) { ... } - public int hashCode() { ... } - public String toString() { return ToStringBuilder.of(A.class)...; } - - public static class Builder { - private final A original; - private final List names; - private int age; - private B.Builder nested = null; - - public Builder(A original) { - this.original = original; - this.names = new ArrayList<>(original.names); - this.age = original.age; - } - - public Builder withName(String name) { this.names.add(name); return this; } - - public int age() { return age; } - public Builder withAge(int age) { this.age = age; return this; } - - private B nested() { return nested==null ? original.nested() : nested.build(); } - public Builder withB(Consumer body) { - if(nested == null) { nested = original.nested.copyOf(); } - body.accept(nested); - return this; - } - public A build() { - A value = new A(this); - return original.equals(value) ? original : value; - } - } -} -``` - -
- - - diff --git a/doc/dev/decisionrecords/RecordsPOJOsBuilders.md b/doc/dev/decisionrecords/RecordsPOJOsBuilders.md new file mode 100644 index 00000000000..34019d503e6 --- /dev/null +++ b/doc/dev/decisionrecords/RecordsPOJOsBuilders.md @@ -0,0 +1,112 @@ +## Records, POJOs and Builders + +We prefer immutable typesafe types over flexibility and "short" class definitions. This makes +the code more robust and less error-prone. References to other entities might need to be mutable, +if so try to init them once, and throw an exception if set again. Example: + +```java +Builder initStop(Stop stop) { + this.stop = requireNotInitialized(this.stop, stop); +} +``` + + +### Records + +You may use records, but avoid using records if you can not encapsulate it properly. Be especially +aware of arrays fields (can not be protected) and collections (remember to make a defensive copy). +If you need to override `equals` and `hashCode`, then it is probably not worth it. +Be aware that `equals` compare references, not the value of a field. Consider overriding `toString`. + +### Builders + +OTP used a simple builder pattern in many places, especially when creating immutable types. + +#### Builder conventions +- Use factory methods to create builder, either `of()` or `copyOf()`. The _copyOf_ uses an existing + instance as its base. The `of()` creates a builder with all default values set. All constructors + should be private (or package local) to enforce the use of the factory methods. +- If the class has more than 5 fields, then avoid using an inner class builder, instead create a + builder in the same package. +- Make all fields in the main class final to enforce immutability. +- Consider using utility methods for parameter checking, like `Objects#requireNonNull` and + `ObjectUtils.ifNotNull`. +- Validate all fields in the main type constructor(i.e. not in the builder), especially null checks. + Prefer default values over null-checks. All business logic using the type can rely on its validity. +- You may keep the original instance in the builder to avoid creating a new object if nothing + changed. This prevents polluting the heap for long-lived objects and make comparison very fast. +- There is no need to provide all get accessors in the Builder if not needed. +- Unit-test builders and verify all fields are copied over. +- For nested builders see the field `nested` in the example. + +
+ Builder example + +```Java +/** + * THIS CLASS IS IMMUTABLE AND THREAD-SAFE + */ +public class A { + public static final A DEFAULT = new A(); + private final List names; + private final int age; + private final B nested; + + private A() { + this.names = List.of("default"); + this.age = 7; + this.nested = B.of(); + } + + private A(Builder builder) { + this.names = List.copyOf(builder.names); + this.age = builder.age; + this.nested = builder.nested(); + + if(age < 0 || age > 150) { + throw new IllegalArgumentException("Age is out of range[0..150]: " + age); + } + } + + public static A.Builder of() { return DEFAULT.copyOf(); } + public A.Builder copyOf() { return new Builder(this); } + + public List listNames() { return names; } + public int age() { return age; } + + public boolean equals(Object other) { ... } + public int hashCode() { ... } + public String toString() { return ToStringBuilder.of(A.class)...; } + + public static class Builder { + private final A original; + private final List names; + private int age; + private B.Builder nested = null; + + public Builder(A original) { + this.original = original; + this.names = new ArrayList<>(original.names); + this.age = original.age; + } + + public Builder withName(String name) { this.names.add(name); return this; } + + public int age() { return age; } + public Builder withAge(int age) { this.age = age; return this; } + + private B nested() { return nested==null ? original.nested() : nested.build(); } + public Builder withB(Consumer body) { + if(nested == null) { nested = original.nested.copyOf(); } + body.accept(nested); + return this; + } + public A build() { + A value = new A(this); + return original.equals(value) ? original : value; + } + } +} +``` + +
diff --git a/doc/dev/decisionrecords/UseDecisionRecords.md b/doc/dev/decisionrecords/UseDecisionRecords.md new file mode 100644 index 00000000000..1900218195e --- /dev/null +++ b/doc/dev/decisionrecords/UseDecisionRecords.md @@ -0,0 +1,37 @@ +# Decision Records + +[TODO - Not precise] An OTP Decision Record is a justified software design choice that addresses a +functional or non-functional requirement that is significant. [Architectural Decision Records](https://adr.github.io/) +is a similar concept, but we have widened the scope to include any relevant decision about the +OTP development. + +## Process + +Decisions we make in the developer meetings are recorded in the [Decision Records](/DECISION_RECORDS.md) +list. If the decision is small and uncontroversial, but yet important and can be expressed in +maximum 2 sentences, we will list it here without any more documentation. If the decision requires +a bit more discussion and explanations, then we will create a PR with a document for it. + +Use the **[template](/doc/dev/decisionrecords/_TEMPLATE.md) as a starting point for documenting +the decision. + + +### How to discuss and document a Decision Record + +- Create a new pull-request and describe the decision record by adding a document to the + `/doc/dev/decisionrecords` folder. Use the [template](/doc/dev/decisionrecords/_TEMPLATE.md). + template. +- Present the decision record in a developer meeting. Make sure to update the main description + based on the feedback/discussion and decisions in the developer meeting. +- The final approval is done in the developer meeting, at least 3 developers representing 3 + different organisations should approve it. No vote against the proposal. If the developers + are not able to agree, the PLC can decide. +- References to Architectural Decision Records in reviews can be done by linking or just typing + e.g. `Use-Dependency-Injection` or [Use-Dependency-Injection](/DECISION_RECORDS.md#use-dependency-injection) + +### Checklist +- [ ] Give it a meaningful title that quickly lets the reader understand what it is all about. +- [ ] Get it approved in a developer meeting with 3 votes in favor (3 organisations). +- [ ] Add the name and description to the list in the [Decision Records](/DECISION_RECORDS.md) list. + Maximum two sentences should be used. Try to keep it as short as possible. +- [ ] Remember to link to the PR. diff --git a/doc/dev/decisionrecords/_TEMPLATE.md b/doc/dev/decisionrecords/_TEMPLATE.md new file mode 100644 index 00000000000..f8389d4a551 --- /dev/null +++ b/doc/dev/decisionrecords/_TEMPLATE.md @@ -0,0 +1,31 @@ +# {TITLE} + +{DESCRIPTION} + + +Original pull-request: {#NNNN} + + +### Context and Problem Statement + + + +### Other options + + - + +### Decision & Consequences + + + +#### Positive Consequences + + - + +#### Negative Consequences + + - diff --git a/docs/Developers-Guide.md b/docs/Developers-Guide.md index 5f834580df8..7d05b723ac8 100644 --- a/docs/Developers-Guide.md +++ b/docs/Developers-Guide.md @@ -199,7 +199,7 @@ formats like 02/01/12. ## Code style -The OTP code style is described on a separate [style guide page](Codestyle.md). +The OTP code style is described on a separate [style guide page](../doc/dev/decisionrecords/Codestyle.md). ## Code conventions and architecture From b04d71e7325735ee68ce09be887b6c36e0b3f51b Mon Sep 17 00:00:00 2001 From: Thomas Gran Date: Fri, 5 Jul 2024 18:05:57 +0200 Subject: [PATCH 11/21] Remove codestyle the published OTP user doc --- mkdocs.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 7925151ac35..586f78566aa 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -90,7 +90,6 @@ nav: - "Developers' Guide": 'Developers-Guide.md' - Localization: 'Localization.md' - Bibliography: 'Bibliography.md' - - Codestyle: 'Codestyle.md' - Sandbox Development: 'SandboxExtension.md' - Release Checklist: 'ReleaseChecklist.md' - Sandbox: From 42a2f80f62896786a3c9e70182ba010785b40fef Mon Sep 17 00:00:00 2001 From: Thomas Gran Date: Fri, 5 Jul 2024 18:12:37 +0200 Subject: [PATCH 12/21] Fix merrge errors --- .github/ISSUE_TEMPLATE/bug_report.md | 27 +++++++++++++++++++ .../workflows/close_stale_pr_and_issues.yml | 4 +-- ISSUE_TEMPLATE/ISSUE_TEMPLATE.md | 27 ------------------- 3 files changed, 28 insertions(+), 30 deletions(-) delete mode 100644 ISSUE_TEMPLATE/ISSUE_TEMPLATE.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index e69de29bb2d..15e9e772595 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,27 @@ +--- +name: Bug report +about: Report a bug or issue +title: '' +labels: '' +assignees: '' + +--- + +**NOTE:** this issue system is intended for reporting bugs and tracking progress in software +development. For all other usage and software development questions or discussion, please post a +question in our chat room: https://gitter.im/opentripplanner/OpenTripPlanner. + + +## Expected behavior + +## Observed behavior + +## Version of OTP used (exact commit hash or JAR name) + +## Data sets in use (links to GTFS and OSM PBF files) + +## Command line used to start OTP + +## Router config and graph build config JSON + +## Steps to reproduce the problem diff --git a/.github/workflows/close_stale_pr_and_issues.yml b/.github/workflows/close_stale_pr_and_issues.yml index 0c337fbc485..98619f7e763 100644 --- a/.github/workflows/close_stale_pr_and_issues.yml +++ b/.github/workflows/close_stale_pr_and_issues.yml @@ -20,7 +20,5 @@ jobs: days-before-stale: 90 days-before-close: 30 operations-per-run: 260 - exempt-issue-labels: - - 'Roadmap' - - 'ADR' + exempt-issue-labels: 'Roadmap' ascending: true diff --git a/ISSUE_TEMPLATE/ISSUE_TEMPLATE.md b/ISSUE_TEMPLATE/ISSUE_TEMPLATE.md deleted file mode 100644 index 15e9e772595..00000000000 --- a/ISSUE_TEMPLATE/ISSUE_TEMPLATE.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -name: Bug report -about: Report a bug or issue -title: '' -labels: '' -assignees: '' - ---- - -**NOTE:** this issue system is intended for reporting bugs and tracking progress in software -development. For all other usage and software development questions or discussion, please post a -question in our chat room: https://gitter.im/opentripplanner/OpenTripPlanner. - - -## Expected behavior - -## Observed behavior - -## Version of OTP used (exact commit hash or JAR name) - -## Data sets in use (links to GTFS and OSM PBF files) - -## Command line used to start OTP - -## Router config and graph build config JSON - -## Steps to reproduce the problem From a3fdb4bf94bdc2a86af499ad931fa13a110596ec Mon Sep 17 00:00:00 2001 From: Thomas Gran Date: Fri, 5 Jul 2024 18:15:15 +0200 Subject: [PATCH 13/21] Update doc/dev/decisionrecords/_TEMPLATE.md --- doc/dev/decisionrecords/_TEMPLATE.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/dev/decisionrecords/_TEMPLATE.md b/doc/dev/decisionrecords/_TEMPLATE.md index f8389d4a551..768430265ff 100644 --- a/doc/dev/decisionrecords/_TEMPLATE.md +++ b/doc/dev/decisionrecords/_TEMPLATE.md @@ -11,8 +11,10 @@ Original pull-request: {#NNNN} ### Context and Problem Statement - + ### Other options From 4c9a8144cb7126c13cc2ff67d1441d22a8652cb6 Mon Sep 17 00:00:00 2001 From: Thomas Gran Date: Wed, 24 Jul 2024 14:59:54 +0200 Subject: [PATCH 14/21] Rename from DECISION_RECORDS to DEVELOPMENT_DECISION_RECORDS --- DECISION_RECORDS.md => DEVELOPMENT_DECISION_RECORDS.md | 2 +- doc/dev/decisionrecords/UseDecisionRecords.md | 2 +- doc/dev/decisionrecords/_TEMPLATE.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) rename DECISION_RECORDS.md => DEVELOPMENT_DECISION_RECORDS.md (99%) diff --git a/DECISION_RECORDS.md b/DEVELOPMENT_DECISION_RECORDS.md similarity index 99% rename from DECISION_RECORDS.md rename to DEVELOPMENT_DECISION_RECORDS.md index dbe044c6168..8ba584e2c57 100644 --- a/DECISION_RECORDS.md +++ b/DEVELOPMENT_DECISION_RECORDS.md @@ -1,4 +1,4 @@ -# Records +# Development Decision Records ## Use-Decision-Records diff --git a/doc/dev/decisionrecords/UseDecisionRecords.md b/doc/dev/decisionrecords/UseDecisionRecords.md index 1900218195e..d30c255e556 100644 --- a/doc/dev/decisionrecords/UseDecisionRecords.md +++ b/doc/dev/decisionrecords/UseDecisionRecords.md @@ -7,7 +7,7 @@ OTP development. ## Process -Decisions we make in the developer meetings are recorded in the [Decision Records](/DECISION_RECORDS.md) +Decisions we make in the developer meetings are recorded in the [Developer Decision Records](/DEVELOPMENT_DECISION_RECORDS.md) list. If the decision is small and uncontroversial, but yet important and can be expressed in maximum 2 sentences, we will list it here without any more documentation. If the decision requires a bit more discussion and explanations, then we will create a PR with a document for it. diff --git a/doc/dev/decisionrecords/_TEMPLATE.md b/doc/dev/decisionrecords/_TEMPLATE.md index 768430265ff..45bb3b11d34 100644 --- a/doc/dev/decisionrecords/_TEMPLATE.md +++ b/doc/dev/decisionrecords/_TEMPLATE.md @@ -2,7 +2,7 @@ {DESCRIPTION} From 77093434b951790f7812ebd3b5a376d5568496ed Mon Sep 17 00:00:00 2001 From: Thomas Gran Date: Wed, 24 Jul 2024 15:00:38 +0200 Subject: [PATCH 15/21] Fix relative links to external developer doc in user doc --- docs/Developers-Guide.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/Developers-Guide.md b/docs/Developers-Guide.md index 3ec7489276d..0b9ec011f96 100644 --- a/docs/Developers-Guide.md +++ b/docs/Developers-Guide.md @@ -197,17 +197,16 @@ Please use only ISO 8601 date format (YYYY-MM-DD) in documentation, comments, an project. This avoids the ambiguity that can result from differing local interpretations of date formats like 02/01/12. -## Code style - -The OTP code style is described on a separate [style guide page](../doc/dev/decisionrecords/Codestyle.md). - ## Code conventions and architecture -The [architecture](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/ARCHITECTURE.md) -and [code conventions](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/CODE_CONVENTIONS.md) -are only available on GitHub, not in the project documentation. These documents contain relative -links to code so, they are a bit easier to maintain that way. The target audience is also active -OTP developers that have the code checked out locally. +The development and architecture documentation are only available on GitHub, not in the user project +documentation (https://www.opentripplanner.org/). These documents contain relative links to code, +so they are a bit easier to maintain that way. The primary audience is also active OTP developers +that have the code checked out locally. + + - [Architecture](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/ARCHITECTURE.md) + - [Code Conventions](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/CODE_CONVENTIONS.md) + - [Development Decision Records](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/DECISION_RECORDS.md) ## Continuous Integration From 564d9b087b9d03978a966cfc4a0be4a1652bc107 Mon Sep 17 00:00:00 2001 From: Thomas Gran Date: Wed, 24 Jul 2024 15:36:14 +0200 Subject: [PATCH 16/21] Move /docs to /doc/user --- .github/pull_request_template.md | 4 +- .github/workflows/cibuild.yml | 2 +- .github/workflows/post-merge.yml | 4 +- .gitignore | 2 +- ARCHITECTURE.md | 4 +- DEVELOPMENT_DECISION_RECORDS.md | 2 +- doc/dev/decisionrecords/Codestyle.md | 2 +- doc/dev/decisionrecords/NamingConventions.md | 2 +- {docs => doc/user}/Accessibility.md | 2 +- {docs => doc/user}/Analysis.md | 0 {docs => doc/user}/Basic-Tutorial.md | 414 +++++++++--------- {docs => doc/user}/Bibliography.md | 0 {docs => doc/user}/BoardingLocations.md | 0 {docs => doc/user}/BuildConfiguration.md | 0 {docs => doc/user}/Changelog.md | 0 {docs => doc/user}/Configuration.md | 0 {docs => doc/user}/Container-Image.md | 0 {docs => doc/user}/Data-Sources.md | 0 {docs => doc/user}/Deployments.md | 192 ++++---- {docs => doc/user}/Developers-Guide.md | 2 +- {docs => doc/user}/Frontends.md | 0 {docs => doc/user}/Getting-OTP.md | 0 {docs => doc/user}/Governance.md | 0 {docs => doc/user}/History.md | 0 {docs => doc/user}/In-Station-Navigation.md | 0 {docs => doc/user}/IslandPruning.md | 0 {docs => doc/user}/Localization.md | 0 {docs => doc/user}/Logging.md | 0 {docs => doc/user}/Migrating-Configuration.md | 0 {docs => doc/user}/Netex-Norway.md | 0 {docs => doc/user}/Preparing-OSM.md | 0 {docs => doc/user}/Presentations.md | 0 {docs => doc/user}/Product-Overview.md | 0 {docs => doc/user}/README-DOCS.txt | 0 {docs => doc/user}/ReleaseChecklist.md | 8 +- {docs => doc/user}/Roadmap.md | 0 {docs => doc/user}/RouteRequest.md | 0 {docs => doc/user}/RouterConfiguration.md | 0 {docs => doc/user}/RoutingModes.md | 0 {docs => doc/user}/SandboxExtension.md | 2 +- {docs => doc/user}/StopAreas.md | 0 {docs => doc/user}/System-Requirements.md | 0 {docs => doc/user}/Troubleshooting-Routing.md | 0 {docs => doc/user}/UpdaterConfig.md | 0 {docs => doc/user}/Version-Comparison.md | 0 {docs => doc/user}/Visual-Identity.md | 0 {docs => doc/user}/apis/Apis.md | 0 {docs => doc/user}/apis/GTFS-GraphQL-API.md | 0 {docs => doc/user}/apis/GraphQL-Tutorial.md | 0 {docs => doc/user}/apis/TransmodelApi.md | 0 {docs => doc/user}/examples/Readme.md | 0 {docs => doc/user}/examples/entur/Readme.md | 0 .../user}/examples/entur/build-config.json | 0 .../user}/examples/entur/otp-config.json | 0 .../user}/examples/entur/router-config.json | 0 .../examples/ibi/atlanta/build-config.json | 0 .../examples/ibi/atlanta/otp-config.json | 0 .../examples/ibi/atlanta/router-config.json | 0 .../examples/ibi/houston/build-config.json | 0 .../examples/ibi/portland/build-config.json | 0 .../examples/ibi/portland/otp-config.json | 0 .../examples/ibi/portland/router-config.json | 0 .../examples/ibi/seattle/build-config.json | 0 .../examples/ibi/seattle/router-config.json | 0 .../examples/ibi/septa/router-config.json | 0 .../user}/examples/skanetrafiken/Readme.md | 0 .../examples/skanetrafiken/build-config.json | 0 .../user}/examples/skanetrafiken/oresund.json | 0 .../examples/skanetrafiken/router-config.json | 0 {docs => doc/user}/github_issue_linker.py | 0 .../user}/images/ExternalToolDialog.png | Bin .../user}/images/ServiceModelOverview.png | Bin {docs => doc/user}/images/TransitTimeLine.svg | 0 {docs => doc/user}/images/badprojection.png | Bin .../user}/images/bicycle-safety-report.png | Bin .../user}/images/boarding-schwabstrasse.png | Bin .../user}/images/buckhead-station.png | Bin {docs => doc/user}/images/cli-flow.svg | 0 .../user}/images/example-isochrone.png | Bin .../user}/images/exiting-oesterfeld.png | Bin .../user}/images/graphiql-autocomplete.png | Bin .../user}/images/graphiql-documentation.png | Bin {docs => doc/user}/images/graphiql.png | Bin {docs => doc/user}/images/nothruisland.png | Bin {docs => doc/user}/images/osmislands.png | Bin {docs => doc/user}/images/otp-logo.svg | 5 +- {docs => doc/user}/images/roadmap-1.png | Bin {docs => doc/user}/images/roadmap-2.png | Bin {docs => doc/user}/images/roadmap-3.png | Bin {docs => doc/user}/images/roadmap-4.png | Bin {docs => doc/user}/images/roadmap-5.png | Bin {docs => doc/user}/images/roadmap-6.png | Bin {docs => doc/user}/images/roadmap-7.png | Bin {docs => doc/user}/images/stationisland.png | Bin {docs => doc/user}/images/stopisland.png | Bin .../user}/images/stopislandproblem.png | Bin {docs => doc/user}/images/transfer-oslo-1.png | Bin {docs => doc/user}/images/transfer-oslo-2.png | Bin .../user}/images/transfer-suedkreuz.png | Bin {docs => doc/user}/images/trueisland.png | Bin {docs => doc/user}/index.md | 152 +++---- {docs => doc/user}/requirements.txt | 0 {docs => doc/user}/sandbox/ActuatorAPI.md | 0 {docs => doc/user}/sandbox/DataOverlay.md | 0 {docs => doc/user}/sandbox/Emissions.md | 0 {docs => doc/user}/sandbox/Fares.md | 0 {docs => doc/user}/sandbox/Flex.md | 0 {docs => doc/user}/sandbox/GeocoderAPI.md | 0 .../user}/sandbox/GoogleCloudStorage.md | 0 .../user}/sandbox/IBIAccessibilityScore.md | 0 .../user}/sandbox/InteractiveOtpMain.md | 0 .../user}/sandbox/MapboxVectorTilesApi.md | 0 {docs => doc/user}/sandbox/ParkAndRideApi.md | 0 {docs => doc/user}/sandbox/ReportApi.md | 0 {docs => doc/user}/sandbox/RideHailing.md | 0 .../user}/sandbox/SmooveBikeRental.md | 0 .../user}/sandbox/StopConsolidation.md | 0 {docs => doc/user}/sandbox/VehicleParking.md | 0 .../sandbox/VehicleRentalServiceDirectory.md | 0 .../user}/sandbox/siri/SiriAzureUpdater.md | 0 .../sandbox/siri/SiriGooglePubSubUpdater.md | 0 .../user}/sandbox/siri/SiriUpdater.md | 0 .../user}/sandbox/transferanalyzer.md | 0 pom.xml | 4 +- .../doc/BuildConfigurationDocTest.java | 2 +- .../generate/doc/ConfigurationDocTest.java | 6 +- .../generate/doc/GraphQLTutorialDocTest.java | 2 +- .../generate/doc/RouteRequestDocTest.java | 2 +- .../doc/RouterConfigurationDocTest.java | 2 +- .../generate/doc/SiriAzureConfigDocTest.java | 2 +- .../generate/doc/SiriConfigDocTest.java | 2 +- .../doc/SiriGooglePubSubConfigDocTest.java | 2 +- .../generate/doc/UpdaterConfigDocTest.java | 2 +- .../doc/framework/DocsTestConstants.java | 4 +- .../standalone/config/ExampleConfigTest.java | 9 +- .../support/FilePatternArgumentsProvider.java | 2 +- 136 files changed, 422 insertions(+), 418 deletions(-) rename {docs => doc/user}/Accessibility.md (99%) rename {docs => doc/user}/Analysis.md (100%) rename {docs => doc/user}/Basic-Tutorial.md (98%) rename {docs => doc/user}/Bibliography.md (100%) rename {docs => doc/user}/BoardingLocations.md (100%) rename {docs => doc/user}/BuildConfiguration.md (100%) rename {docs => doc/user}/Changelog.md (100%) rename {docs => doc/user}/Configuration.md (100%) rename {docs => doc/user}/Container-Image.md (100%) rename {docs => doc/user}/Data-Sources.md (100%) rename {docs => doc/user}/Deployments.md (98%) rename {docs => doc/user}/Developers-Guide.md (99%) rename {docs => doc/user}/Frontends.md (100%) rename {docs => doc/user}/Getting-OTP.md (100%) rename {docs => doc/user}/Governance.md (100%) rename {docs => doc/user}/History.md (100%) rename {docs => doc/user}/In-Station-Navigation.md (100%) rename {docs => doc/user}/IslandPruning.md (100%) rename {docs => doc/user}/Localization.md (100%) rename {docs => doc/user}/Logging.md (100%) rename {docs => doc/user}/Migrating-Configuration.md (100%) rename {docs => doc/user}/Netex-Norway.md (100%) rename {docs => doc/user}/Preparing-OSM.md (100%) rename {docs => doc/user}/Presentations.md (100%) rename {docs => doc/user}/Product-Overview.md (100%) rename {docs => doc/user}/README-DOCS.txt (100%) rename {docs => doc/user}/ReleaseChecklist.md (96%) rename {docs => doc/user}/Roadmap.md (100%) rename {docs => doc/user}/RouteRequest.md (100%) rename {docs => doc/user}/RouterConfiguration.md (100%) rename {docs => doc/user}/RoutingModes.md (100%) rename {docs => doc/user}/SandboxExtension.md (97%) rename {docs => doc/user}/StopAreas.md (100%) rename {docs => doc/user}/System-Requirements.md (100%) rename {docs => doc/user}/Troubleshooting-Routing.md (100%) rename {docs => doc/user}/UpdaterConfig.md (100%) rename {docs => doc/user}/Version-Comparison.md (100%) rename {docs => doc/user}/Visual-Identity.md (100%) rename {docs => doc/user}/apis/Apis.md (100%) rename {docs => doc/user}/apis/GTFS-GraphQL-API.md (100%) rename {docs => doc/user}/apis/GraphQL-Tutorial.md (100%) rename {docs => doc/user}/apis/TransmodelApi.md (100%) rename {docs => doc/user}/examples/Readme.md (100%) rename {docs => doc/user}/examples/entur/Readme.md (100%) rename {docs => doc/user}/examples/entur/build-config.json (100%) rename {docs => doc/user}/examples/entur/otp-config.json (100%) rename {docs => doc/user}/examples/entur/router-config.json (100%) rename {docs => doc/user}/examples/ibi/atlanta/build-config.json (100%) rename {docs => doc/user}/examples/ibi/atlanta/otp-config.json (100%) rename {docs => doc/user}/examples/ibi/atlanta/router-config.json (100%) rename {docs => doc/user}/examples/ibi/houston/build-config.json (100%) rename {docs => doc/user}/examples/ibi/portland/build-config.json (100%) rename {docs => doc/user}/examples/ibi/portland/otp-config.json (100%) rename {docs => doc/user}/examples/ibi/portland/router-config.json (100%) rename {docs => doc/user}/examples/ibi/seattle/build-config.json (100%) rename {docs => doc/user}/examples/ibi/seattle/router-config.json (100%) rename {docs => doc/user}/examples/ibi/septa/router-config.json (100%) rename {docs => doc/user}/examples/skanetrafiken/Readme.md (100%) rename {docs => doc/user}/examples/skanetrafiken/build-config.json (100%) rename {docs => doc/user}/examples/skanetrafiken/oresund.json (100%) rename {docs => doc/user}/examples/skanetrafiken/router-config.json (100%) rename {docs => doc/user}/github_issue_linker.py (100%) rename {docs => doc/user}/images/ExternalToolDialog.png (100%) rename {docs => doc/user}/images/ServiceModelOverview.png (100%) rename {docs => doc/user}/images/TransitTimeLine.svg (100%) rename {docs => doc/user}/images/badprojection.png (100%) rename {docs => doc/user}/images/bicycle-safety-report.png (100%) rename {docs => doc/user}/images/boarding-schwabstrasse.png (100%) rename {docs => doc/user}/images/buckhead-station.png (100%) rename {docs => doc/user}/images/cli-flow.svg (100%) rename {docs => doc/user}/images/example-isochrone.png (100%) rename {docs => doc/user}/images/exiting-oesterfeld.png (100%) rename {docs => doc/user}/images/graphiql-autocomplete.png (100%) rename {docs => doc/user}/images/graphiql-documentation.png (100%) rename {docs => doc/user}/images/graphiql.png (100%) rename {docs => doc/user}/images/nothruisland.png (100%) rename {docs => doc/user}/images/osmislands.png (100%) rename {docs => doc/user}/images/otp-logo.svg (87%) rename {docs => doc/user}/images/roadmap-1.png (100%) rename {docs => doc/user}/images/roadmap-2.png (100%) rename {docs => doc/user}/images/roadmap-3.png (100%) rename {docs => doc/user}/images/roadmap-4.png (100%) rename {docs => doc/user}/images/roadmap-5.png (100%) rename {docs => doc/user}/images/roadmap-6.png (100%) rename {docs => doc/user}/images/roadmap-7.png (100%) rename {docs => doc/user}/images/stationisland.png (100%) rename {docs => doc/user}/images/stopisland.png (100%) rename {docs => doc/user}/images/stopislandproblem.png (100%) rename {docs => doc/user}/images/transfer-oslo-1.png (100%) rename {docs => doc/user}/images/transfer-oslo-2.png (100%) rename {docs => doc/user}/images/transfer-suedkreuz.png (100%) rename {docs => doc/user}/images/trueisland.png (100%) rename {docs => doc/user}/index.md (98%) rename {docs => doc/user}/requirements.txt (100%) rename {docs => doc/user}/sandbox/ActuatorAPI.md (100%) rename {docs => doc/user}/sandbox/DataOverlay.md (100%) rename {docs => doc/user}/sandbox/Emissions.md (100%) rename {docs => doc/user}/sandbox/Fares.md (100%) rename {docs => doc/user}/sandbox/Flex.md (100%) rename {docs => doc/user}/sandbox/GeocoderAPI.md (100%) rename {docs => doc/user}/sandbox/GoogleCloudStorage.md (100%) rename {docs => doc/user}/sandbox/IBIAccessibilityScore.md (100%) rename {docs => doc/user}/sandbox/InteractiveOtpMain.md (100%) rename {docs => doc/user}/sandbox/MapboxVectorTilesApi.md (100%) rename {docs => doc/user}/sandbox/ParkAndRideApi.md (100%) rename {docs => doc/user}/sandbox/ReportApi.md (100%) rename {docs => doc/user}/sandbox/RideHailing.md (100%) rename {docs => doc/user}/sandbox/SmooveBikeRental.md (100%) rename {docs => doc/user}/sandbox/StopConsolidation.md (100%) rename {docs => doc/user}/sandbox/VehicleParking.md (100%) rename {docs => doc/user}/sandbox/VehicleRentalServiceDirectory.md (100%) rename {docs => doc/user}/sandbox/siri/SiriAzureUpdater.md (100%) rename {docs => doc/user}/sandbox/siri/SiriGooglePubSubUpdater.md (100%) rename {docs => doc/user}/sandbox/siri/SiriUpdater.md (100%) rename {docs => doc/user}/sandbox/transferanalyzer.md (100%) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index da79a466e0b..a67cae22195 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -47,7 +47,7 @@ Write a few words on how the new code is tested. - Was the code designed so it is unit testable? - Were any tests applied to the smallest appropriate unit? - Do all tests - pass [the continuous integration service](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/docs/Developers-Guide.md#continuous-integration) + pass [the continuous integration service](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/doc/user/Developers-Guide.md#continuous-integration) ? ### Documentation @@ -59,7 +59,7 @@ Write a few words on how the new code is tested. ### Changelog -The [changelog file](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/docs/Changelog.md) +The [changelog file](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/doc/user/Changelog.md) is generated from the pull-request title, make sure the title describe the feature or issue fixed. To exclude the PR from the changelog add the label `skip changelog` to the PR. diff --git a/.github/workflows/cibuild.yml b/.github/workflows/cibuild.yml index 4b814d03e35..89bc77b2b97 100644 --- a/.github/workflows/cibuild.yml +++ b/.github/workflows/cibuild.yml @@ -108,7 +108,7 @@ jobs: if: github.event_name == 'pull_request' - name: Install Python dependencies - run: pip install -r docs/requirements.txt + run: pip install -r doc/user/requirements.txt - name: Build main documentation diff --git a/.github/workflows/post-merge.yml b/.github/workflows/post-merge.yml index 86f3741aada..b26198e99a6 100644 --- a/.github/workflows/post-merge.yml +++ b/.github/workflows/post-merge.yml @@ -29,8 +29,8 @@ jobs: run: | # add a line above the one which contains AUTOMATIC_CHANGELOG_PLACEHOLDER ITEM="${TITLE} [#${NUMBER}](${URL})" - TEMP_FILE=docs/Changelog.generated.md - FILE=docs/Changelog.md + TEMP_FILE=doc/user/Changelog.generated.md + FILE=doc/user/Changelog.md awk "/CHANGELOG_PLACEHOLDER/{print \"- $ITEM\"}1" $FILE > $TEMP_FILE mv $TEMP_FILE $FILE git add $FILE diff --git a/.gitignore b/.gitignore index a90f06cdcb0..6fac28d2178 100644 --- a/.gitignore +++ b/.gitignore @@ -30,7 +30,7 @@ o_o_standalone_config_IncludeFileDirectiveTest_part.json _site/ build/ dist/ -docs/_build/ +doc/user/_build/ gen-java/ gen-javabean/ gen-py/ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 1cf652ddb87..8df085f3b5d 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -15,14 +15,14 @@ We document [Decision Records](DECISION_RECORDS.md) in a log. Make sure you as a with the decisions and follow them. Reviewers should use them actively when reviewing code and may use them to ask for changes. -Be sure to also read the [developer documentation](docs/Developers-Guide.md). +Be sure to also read the [developer documentation](doc/user/Developers-Guide.md). ## Modules/Components The diagram shows a simplified/generic version on how we want to model the OTP components with 2 examples. The Transit model is more complex than the VehiclePosition model. -![MainModelOverview](docs/images/ServiceModelOverview.png) +![MainModelOverview](doc/user/images/ServiceModelOverview.png) - `Use Case Service` A service which combine the functionality in many `Domain Services` to fulfill a use-case or set of features. It may have an api with request/response classes. These are diff --git a/DEVELOPMENT_DECISION_RECORDS.md b/DEVELOPMENT_DECISION_RECORDS.md index 8ba584e2c57..10b9e005809 100644 --- a/DEVELOPMENT_DECISION_RECORDS.md +++ b/DEVELOPMENT_DECISION_RECORDS.md @@ -31,7 +31,7 @@ notes on `private` members and as inline comments. > If you decide to NOT follow these decision records, then you must document why. **See also** - - [Developers-Guide > Code comments](docs/Developers-Guide.md#code-comments). + - [Developers-Guide > Code comments](doc/user/Developers-Guide.md#code-comments). - [Codestyle > Javadoc Guidlines](doc/dev/decisionrecords/Codestyle.md#javadoc-guidlines) - JavaDoc checklist diff --git a/doc/dev/decisionrecords/Codestyle.md b/doc/dev/decisionrecords/Codestyle.md index bdeab50a283..3aa93c86125 100644 --- a/doc/dev/decisionrecords/Codestyle.md +++ b/doc/dev/decisionrecords/Codestyle.md @@ -58,7 +58,7 @@ Editor > Code Style_. Then select **Project** in the \_Scheme drop down. You can run the Prettier Maven plugin as an external tool in IntelliJ. Set it up as an `External tool` and assign a key-shortcut to the tool execution. -![External Tool Dialog](../../../docs/images/ExternalToolDialog.png) +![External Tool Dialog](../../../doc/user/images/ExternalToolDialog.png) ``` Name: Prettier Format Current File diff --git a/doc/dev/decisionrecords/NamingConventions.md b/doc/dev/decisionrecords/NamingConventions.md index f186d57576a..3a226fa47ae 100644 --- a/doc/dev/decisionrecords/NamingConventions.md +++ b/doc/dev/decisionrecords/NamingConventions.md @@ -60,7 +60,7 @@ These prefixes are also "allowed", but not preferred - they have some kind of ne ## Service, Model and Repository -![MainModelOverview](docs/images/ServiceModelOverview.png) +![MainModelOverview](doc/user/images/ServiceModelOverview.png) diff --git a/docs/Accessibility.md b/doc/user/Accessibility.md similarity index 99% rename from docs/Accessibility.md rename to doc/user/Accessibility.md index 49373c522c2..27cb47ce92e 100644 --- a/docs/Accessibility.md +++ b/doc/user/Accessibility.md @@ -109,4 +109,4 @@ inaccessible to wheelchair users. ## Example A full configuration example is available -at [`/docs/examples`](https://github.com/opentripplanner/OpenTripPlanner/tree/dev-2.x/docs/examples/ibi) \ No newline at end of file +at [`/docs/examples`](https://github.com/opentripplanner/OpenTripPlanner/tree/dev-2.x/doc/user/examples/ibi) \ No newline at end of file diff --git a/docs/Analysis.md b/doc/user/Analysis.md similarity index 100% rename from docs/Analysis.md rename to doc/user/Analysis.md diff --git a/docs/Basic-Tutorial.md b/doc/user/Basic-Tutorial.md similarity index 98% rename from docs/Basic-Tutorial.md rename to doc/user/Basic-Tutorial.md index a7a69b8a3bb..d6e46f3f1f5 100644 --- a/docs/Basic-Tutorial.md +++ b/doc/user/Basic-Tutorial.md @@ -1,207 +1,207 @@ -# OpenTripPlanner Basic Tutorial - -This page should allow you to set up and test your own OTP2 server. If all goes well it should only -take a few minutes! - -## Get Java - -As a Java program, OTP must be run within a Java virtual machine (JVM), which is provided as part of -the Java runtime (JRE) or Java development kit (JDK). OTP2 is compatible with Java 21 or later. We -recommend running on Java 21 rather than a later version, as it is a long-term support release. -Run `java -version` to check that you have version 21 or newer of the JVM installed. If you do not, -you will need to install a recent OpenJDK or Oracle Java package for your operating system. - -## Get OTP - -OpenTripPlanner is written in Java and distributed as a single runnable JAR file. This is a "shaded" -JAR containing all other libraries needed for OTP to work, and is available from the Maven Central -repository. You will be able to go -to [the OTP directory at Maven Central](https://repo1.maven.org/maven2/org/opentripplanner/otp/), -navigate to -the [directory of releases](https://repo1.maven.org/maven2/org/opentripplanner/otp/2.5.0/), -and download -the [file with `shaded.jar` suffix](https://repo1.maven.org/maven2/org/opentripplanner/otp/2.5.0/otp-2.5.0-shaded.jar) -. - -You may also want to get your own copy of the OTP source code -and [build a bleeding edge development JAR from scratch](Getting-OTP.md), especially if you plan to -do some development yourself. In that case, check out the branch `dev-2.x`. - -## Get some data - -### GTFS for Transit Schedules and Stops - -First you'll need GTFS data to build a transit network. There's an excellent description of the GTFS -format [here](http://gtfs.org/). Transport agencies throughout the world provide GTFS schedules to -the public. Transitland has a -[registry of feeds](https://transit.land/feed-registry) and [TransitFeeds](http://transitfeeds.com/) -also provides an extensive catalog. The best option is often to simply fetch the data directly from -a transit operator or agency. If you know of a feed you want to work with, download it and put it in -an empty directory you have created for your OTP instance such as `/home/username/otp` on -Linux, `/Users/username/otp` on MacOS, or `C:\Users\username\otp` on Windows. For OTP2 to detect a -GTFS file, **its name must end in `.zip` and must contain the letters 'gtfs'**. We often use the -convention of saving GTFS files with names ending in `.gtfs.zip` which meets both these criteria, -reflecting the fact that a GTFS feed is just a ZIP file containing a specific set of files. If you -don't have a particular feed in mind, the one for Portland, Oregon's TriMet agency is a good option. -It is available at [this URL](http://developer.trimet.org/schedule/gtfs.zip). This is a -moderate-sized input of good quality (TriMet initiated OTP development and helped develop the GTFS -format). On Linux, this could be done on the command line as follows: - - $ cd /home/username - $ mkdir otp - $ cd otp - $ wget "http://developer.trimet.org/schedule/gtfs.zip" -O trimet.gtfs.zip - -### OSM for Streets - -You'll also need OpenStreetMap data to build a road network for walking, cycling, and -driving. [OpenStreetMap](https://www.openstreetmap.org/) is a global collaborative map database that -rivals or surpasses the quality of commercial maps in many locations. Several services extract -smaller geographic regions from this database. Interline Technologies maintains a collection -of [extracts updated daily for urban areas around the world](https://www.interline.io/osm/extracts/) -. [Geofabrik](http://download.geofabrik.de/) provides extracts for larger areas like countries or -states, from which you can prepare your own smaller bounding-box extracts -using [Osmosis](http://wiki.openstreetmap.org/wiki/Osmosis#Extracting_bounding_boxes) -, [osmconvert](http://wiki.openstreetmap.org/wiki/Osmconvert#Applying_Geographical_Borders), or (our -favorite) [Osmium-Tool](https://osmcode.org/osmium-tool/manual.html#creating-geographic-extracts). -There is also [Protomaps](https://app.protomaps.com/) which can create custom extracts -for any region of the world with an easy to use drag and drop interface. -OSM data can be delivered as XML or in the more compact binary PBF format. OpenTripPlanner consumes -only PBF because it's smaller and more efficient. - -Download OSM PBF data for the same geographic region as your GTFS feed, and place this PBF file in -the same directory you created for the OSM data. If you are using the TriMet GTFS feed, you could -download -the [Geofabrik extract for the US state of Oregon](http://download.geofabrik.de/north-america/us/oregon.html) -, then further trim that to just -the [TriMet service area](https://trimet.org/pdfs/taxinfo/trimetdistrictboundary.pdf) using the -bounding box switch of one of the above tools. On Linux or MacOS you could do that as follows: - - $ cd /home/username - $ wget http://download.geofabrik.de/north-america/us/oregon-latest.osm.pbf - $ osmconvert oregon-latest.osm.pbf -b=-123.043,45.246,-122.276,45.652 --complete-ways -o=portland.pbf - $ mv portland.pbf otp - -We find [this tool](https://boundingbox.klokantech.com/) useful for determining the geographic -coordinates of bounding boxes. The CSV option in that tool produces exactly the format expected by -the `osmconvert -b` switch. The `--complete-ways` switch is important to handle roads that cross -outside your bounding box. - -If you have extracted a smaller PBF file from a larger region, be sure to put only your extract (not -the original larger file) in the directory with your GTFS data. Otherwise OTP will try to load both -the original file and the extract in a later step. See -the [page on preparing OSM data](Preparing-OSM.md) for additional information and example commands -for cropping and filtering OSM data. - -## Starting OTP - -A typical command to start OTP looks like `java -Xmx2G -jar otp.shaded.jar `. The -`-Xmx` parameter sets the limit on how much memory OTP is allowed to consume. GTFS and OSM data sets -are often very large, and OTP is relatively memory-hungry. You will need at least 1GB of memory when -working with the Portland TriMet data set, and several gigabytes for larger inputs. -[Here is more information about the system requirements](System-Requirements.md). If you have -sufficient memory in your computer, set this to a couple of gigabytes (e.g. `-Xmx2G`). Java uses -a [garbage collection](https://en.wikipedia.org/wiki/Garbage_collection_(computer_science)) approach -to memory management, which requires some "breathing room" to efficiently operate. Without -sufficient free memory OTP can grind to a halt. [VisualVM](https://visualvm.github.io) is a good way -to inspect Java memory usage, especially with -the [VisualGC plugin](https://visualvm.github.io/plugins.html). - -## Building Graphs - -There are two main phases to preparing and deploying an OTP server. The first is to analyze the -GTFS, OSM and any other inputs (such as elevation data) and build a representation of the -transportation network. Following mathematical terminology we call this -a ['graph'](http://en.wikipedia.org/wiki/Graph_%28mathematics%29), and refer to this phase as "graph -building". The second phase is to start a server that provides trip planning and other API services -for this graph. - -It is possible to save the graph to a file on disk after the first phase, then load the graph from -the file in the second phase. This allows restarting the server or starting multiple instances of -the server without repeating the often time-consuming process of building the graph. It is also -possible to split the graph building process into separate OSM and GTFS stages for similar reasons: -to allow reusing results from slow processes, such as applying elevation data to streets. These -different options are controlled with command line switches, and will be described in more detail -below and in other tutorials. - -## Simple One-step Server - -The simplest way to use OTP is to build a graph in a single step and start a server immediately, -without saving it to disk. The command to do so is: - - $ java -Xmx2G -jar otp-2.5.0-shaded.jar --build --serve /home/username/otp - -where `/home/username/otp` should be the directory where you put your configuration and input files. - -If you're using the Portland input data, the graph build operation should take about one minute to -complete, and then you'll see a `Grizzly server running` message. At this point you have an -OpenTripPlanner server running locally and can open [http://localhost:8080/](http://localhost:8080/) -in a web browser. You should be presented with a Javascript client application that will interact -with your local OpenTripPlanner instance. - -This map-based user interface is in fact sending HTTP GET requests to the OTP server running on your -local machine. It can be informative to watch the HTTP requests and responses being generated using -the developer tools in your web browser. OTP's built-in web server will run by default on port 8080. -If by any chance some other software is already using that port number, you can specify a different -port number with a switch -`--port 8801`. - - -## Saving a Graph - -If you want speed up the process of repeatedly starting up a server with the same graph, you can -build a graph from street and transit data then save it to a file using the `--build` and `--save` -command line parameters together. If for example your current working directory (`.`) contains the -input files and the OTP JAR file, you can use this command: - - $ java -Xmx2G -jar otp-2.5.0-shaded.jar --build --save . - -This will produce a file called `graph.obj` in the same directory as the inputs. The server can then -be started later using the `--load` parameter, and will read this file instead of building the graph -from scratch: - - $ java -Xmx2G -jar otp-2.5.0-shaded.jar --load . - -Another reason to perform these two phases separately is that the building process loads the entire -GTFS and OSM data sets into memory, so can require significantly more memory than just running a -server. Accordingly, you may want to perform the build on one machine (e.g. a throw-away cloud -instance with more memory or compute capacity), then copy the resulting graph file to one or more -smaller machines to serve the API. - -## Layering GTFS onto OSM - -Building the street graph (especially with elevation data) can take a long time. It is common for -transit data to change more frequently than street data, so it can be convenient to build the street -graph once, and then layer transit data on top of the streets to make the final graph. - -Again assuming the input files and OTP JAR file are in the current working directory, you can build -a street graph with OSM and elevation data only (ignoring transit input files) with this command: - - $ java -Xmx2G -jar otp-2.5.0-shaded.jar --buildStreet . - -Then, to build a graph layering transit data on top of the saved street graph (built using the -previous command): - - $ java -Xmx2G -jar otp-2.5.0-shaded.jar --loadStreet --save . - -Finally, the server can be started using the `--load` parameter: - - $ java -Xmx2G -jar otp-2.5.0-shaded.jar --load . - -## Command Line Switches - -The flow diagram below summarizes all the command line switches used in the above examples, and how -they control which actions are taken when OTP starts up. - -![Command-Line-Parameter-Flow](images/cli-flow.svg) - -You must use at least one of the required parameters: `--load`, `--loadStreet`, `--build` -, `--buildStreet`. A _required_ parameter may imply other parameters when the flow allows for no -other choice. For example, `--load` implies `--serve`, so `--serve` is not necessary and has no -additional effect when used together with `--load`. - -You can run the OTP .jar file with the `--help` option for a full list of command line parameters. - -## Exploring the API - -If you want to learn how to use OTP's API's, check out the [GraphQL tutorial](apis/GraphQL-Tutorial.md). +# OpenTripPlanner Basic Tutorial + +This page should allow you to set up and test your own OTP2 server. If all goes well it should only +take a few minutes! + +## Get Java + +As a Java program, OTP must be run within a Java virtual machine (JVM), which is provided as part of +the Java runtime (JRE) or Java development kit (JDK). OTP2 is compatible with Java 21 or later. We +recommend running on Java 21 rather than a later version, as it is a long-term support release. +Run `java -version` to check that you have version 21 or newer of the JVM installed. If you do not, +you will need to install a recent OpenJDK or Oracle Java package for your operating system. + +## Get OTP + +OpenTripPlanner is written in Java and distributed as a single runnable JAR file. This is a "shaded" +JAR containing all other libraries needed for OTP to work, and is available from the Maven Central +repository. You will be able to go +to [the OTP directory at Maven Central](https://repo1.maven.org/maven2/org/opentripplanner/otp/), +navigate to +the [directory of releases](https://repo1.maven.org/maven2/org/opentripplanner/otp/2.5.0/), +and download +the [file with `shaded.jar` suffix](https://repo1.maven.org/maven2/org/opentripplanner/otp/2.5.0/otp-2.5.0-shaded.jar) +. + +You may also want to get your own copy of the OTP source code +and [build a bleeding edge development JAR from scratch](Getting-OTP.md), especially if you plan to +do some development yourself. In that case, check out the branch `dev-2.x`. + +## Get some data + +### GTFS for Transit Schedules and Stops + +First you'll need GTFS data to build a transit network. There's an excellent description of the GTFS +format [here](http://gtfs.org/). Transport agencies throughout the world provide GTFS schedules to +the public. Transitland has a +[registry of feeds](https://transit.land/feed-registry) and [TransitFeeds](http://transitfeeds.com/) +also provides an extensive catalog. The best option is often to simply fetch the data directly from +a transit operator or agency. If you know of a feed you want to work with, download it and put it in +an empty directory you have created for your OTP instance such as `/home/username/otp` on +Linux, `/Users/username/otp` on MacOS, or `C:\Users\username\otp` on Windows. For OTP2 to detect a +GTFS file, **its name must end in `.zip` and must contain the letters 'gtfs'**. We often use the +convention of saving GTFS files with names ending in `.gtfs.zip` which meets both these criteria, +reflecting the fact that a GTFS feed is just a ZIP file containing a specific set of files. If you +don't have a particular feed in mind, the one for Portland, Oregon's TriMet agency is a good option. +It is available at [this URL](http://developer.trimet.org/schedule/gtfs.zip). This is a +moderate-sized input of good quality (TriMet initiated OTP development and helped develop the GTFS +format). On Linux, this could be done on the command line as follows: + + $ cd /home/username + $ mkdir otp + $ cd otp + $ wget "http://developer.trimet.org/schedule/gtfs.zip" -O trimet.gtfs.zip + +### OSM for Streets + +You'll also need OpenStreetMap data to build a road network for walking, cycling, and +driving. [OpenStreetMap](https://www.openstreetmap.org/) is a global collaborative map database that +rivals or surpasses the quality of commercial maps in many locations. Several services extract +smaller geographic regions from this database. Interline Technologies maintains a collection +of [extracts updated daily for urban areas around the world](https://www.interline.io/osm/extracts/) +. [Geofabrik](http://download.geofabrik.de/) provides extracts for larger areas like countries or +states, from which you can prepare your own smaller bounding-box extracts +using [Osmosis](http://wiki.openstreetmap.org/wiki/Osmosis#Extracting_bounding_boxes) +, [osmconvert](http://wiki.openstreetmap.org/wiki/Osmconvert#Applying_Geographical_Borders), or (our +favorite) [Osmium-Tool](https://osmcode.org/osmium-tool/manual.html#creating-geographic-extracts). +There is also [Protomaps](https://app.protomaps.com/) which can create custom extracts +for any region of the world with an easy to use drag and drop interface. +OSM data can be delivered as XML or in the more compact binary PBF format. OpenTripPlanner consumes +only PBF because it's smaller and more efficient. + +Download OSM PBF data for the same geographic region as your GTFS feed, and place this PBF file in +the same directory you created for the OSM data. If you are using the TriMet GTFS feed, you could +download +the [Geofabrik extract for the US state of Oregon](http://download.geofabrik.de/north-america/us/oregon.html) +, then further trim that to just +the [TriMet service area](https://trimet.org/pdfs/taxinfo/trimetdistrictboundary.pdf) using the +bounding box switch of one of the above tools. On Linux or MacOS you could do that as follows: + + $ cd /home/username + $ wget http://download.geofabrik.de/north-america/us/oregon-latest.osm.pbf + $ osmconvert oregon-latest.osm.pbf -b=-123.043,45.246,-122.276,45.652 --complete-ways -o=portland.pbf + $ mv portland.pbf otp + +We find [this tool](https://boundingbox.klokantech.com/) useful for determining the geographic +coordinates of bounding boxes. The CSV option in that tool produces exactly the format expected by +the `osmconvert -b` switch. The `--complete-ways` switch is important to handle roads that cross +outside your bounding box. + +If you have extracted a smaller PBF file from a larger region, be sure to put only your extract (not +the original larger file) in the directory with your GTFS data. Otherwise OTP will try to load both +the original file and the extract in a later step. See +the [page on preparing OSM data](Preparing-OSM.md) for additional information and example commands +for cropping and filtering OSM data. + +## Starting OTP + +A typical command to start OTP looks like `java -Xmx2G -jar otp.shaded.jar `. The +`-Xmx` parameter sets the limit on how much memory OTP is allowed to consume. GTFS and OSM data sets +are often very large, and OTP is relatively memory-hungry. You will need at least 1GB of memory when +working with the Portland TriMet data set, and several gigabytes for larger inputs. +[Here is more information about the system requirements](System-Requirements.md). If you have +sufficient memory in your computer, set this to a couple of gigabytes (e.g. `-Xmx2G`). Java uses +a [garbage collection](https://en.wikipedia.org/wiki/Garbage_collection_(computer_science)) approach +to memory management, which requires some "breathing room" to efficiently operate. Without +sufficient free memory OTP can grind to a halt. [VisualVM](https://visualvm.github.io) is a good way +to inspect Java memory usage, especially with +the [VisualGC plugin](https://visualvm.github.io/plugins.html). + +## Building Graphs + +There are two main phases to preparing and deploying an OTP server. The first is to analyze the +GTFS, OSM and any other inputs (such as elevation data) and build a representation of the +transportation network. Following mathematical terminology we call this +a ['graph'](http://en.wikipedia.org/wiki/Graph_%28mathematics%29), and refer to this phase as "graph +building". The second phase is to start a server that provides trip planning and other API services +for this graph. + +It is possible to save the graph to a file on disk after the first phase, then load the graph from +the file in the second phase. This allows restarting the server or starting multiple instances of +the server without repeating the often time-consuming process of building the graph. It is also +possible to split the graph building process into separate OSM and GTFS stages for similar reasons: +to allow reusing results from slow processes, such as applying elevation data to streets. These +different options are controlled with command line switches, and will be described in more detail +below and in other tutorials. + +## Simple One-step Server + +The simplest way to use OTP is to build a graph in a single step and start a server immediately, +without saving it to disk. The command to do so is: + + $ java -Xmx2G -jar otp-2.5.0-shaded.jar --build --serve /home/username/otp + +where `/home/username/otp` should be the directory where you put your configuration and input files. + +If you're using the Portland input data, the graph build operation should take about one minute to +complete, and then you'll see a `Grizzly server running` message. At this point you have an +OpenTripPlanner server running locally and can open [http://localhost:8080/](http://localhost:8080/) +in a web browser. You should be presented with a Javascript client application that will interact +with your local OpenTripPlanner instance. + +This map-based user interface is in fact sending HTTP GET requests to the OTP server running on your +local machine. It can be informative to watch the HTTP requests and responses being generated using +the developer tools in your web browser. OTP's built-in web server will run by default on port 8080. +If by any chance some other software is already using that port number, you can specify a different +port number with a switch +`--port 8801`. + + +## Saving a Graph + +If you want speed up the process of repeatedly starting up a server with the same graph, you can +build a graph from street and transit data then save it to a file using the `--build` and `--save` +command line parameters together. If for example your current working directory (`.`) contains the +input files and the OTP JAR file, you can use this command: + + $ java -Xmx2G -jar otp-2.5.0-shaded.jar --build --save . + +This will produce a file called `graph.obj` in the same directory as the inputs. The server can then +be started later using the `--load` parameter, and will read this file instead of building the graph +from scratch: + + $ java -Xmx2G -jar otp-2.5.0-shaded.jar --load . + +Another reason to perform these two phases separately is that the building process loads the entire +GTFS and OSM data sets into memory, so can require significantly more memory than just running a +server. Accordingly, you may want to perform the build on one machine (e.g. a throw-away cloud +instance with more memory or compute capacity), then copy the resulting graph file to one or more +smaller machines to serve the API. + +## Layering GTFS onto OSM + +Building the street graph (especially with elevation data) can take a long time. It is common for +transit data to change more frequently than street data, so it can be convenient to build the street +graph once, and then layer transit data on top of the streets to make the final graph. + +Again assuming the input files and OTP JAR file are in the current working directory, you can build +a street graph with OSM and elevation data only (ignoring transit input files) with this command: + + $ java -Xmx2G -jar otp-2.5.0-shaded.jar --buildStreet . + +Then, to build a graph layering transit data on top of the saved street graph (built using the +previous command): + + $ java -Xmx2G -jar otp-2.5.0-shaded.jar --loadStreet --save . + +Finally, the server can be started using the `--load` parameter: + + $ java -Xmx2G -jar otp-2.5.0-shaded.jar --load . + +## Command Line Switches + +The flow diagram below summarizes all the command line switches used in the above examples, and how +they control which actions are taken when OTP starts up. + +![Command-Line-Parameter-Flow](images/cli-flow.svg) + +You must use at least one of the required parameters: `--load`, `--loadStreet`, `--build` +, `--buildStreet`. A _required_ parameter may imply other parameters when the flow allows for no +other choice. For example, `--load` implies `--serve`, so `--serve` is not necessary and has no +additional effect when used together with `--load`. + +You can run the OTP .jar file with the `--help` option for a full list of command line parameters. + +## Exploring the API + +If you want to learn how to use OTP's API's, check out the [GraphQL tutorial](apis/GraphQL-Tutorial.md). diff --git a/docs/Bibliography.md b/doc/user/Bibliography.md similarity index 100% rename from docs/Bibliography.md rename to doc/user/Bibliography.md diff --git a/docs/BoardingLocations.md b/doc/user/BoardingLocations.md similarity index 100% rename from docs/BoardingLocations.md rename to doc/user/BoardingLocations.md diff --git a/docs/BuildConfiguration.md b/doc/user/BuildConfiguration.md similarity index 100% rename from docs/BuildConfiguration.md rename to doc/user/BuildConfiguration.md diff --git a/docs/Changelog.md b/doc/user/Changelog.md similarity index 100% rename from docs/Changelog.md rename to doc/user/Changelog.md diff --git a/docs/Configuration.md b/doc/user/Configuration.md similarity index 100% rename from docs/Configuration.md rename to doc/user/Configuration.md diff --git a/docs/Container-Image.md b/doc/user/Container-Image.md similarity index 100% rename from docs/Container-Image.md rename to doc/user/Container-Image.md diff --git a/docs/Data-Sources.md b/doc/user/Data-Sources.md similarity index 100% rename from docs/Data-Sources.md rename to doc/user/Data-Sources.md diff --git a/docs/Deployments.md b/doc/user/Deployments.md similarity index 98% rename from docs/Deployments.md rename to doc/user/Deployments.md index d1df3984b05..56ff23c113c 100644 --- a/docs/Deployments.md +++ b/doc/user/Deployments.md @@ -1,96 +1,96 @@ -# OpenTripPlanner Deployments Worldwide - -## Official Production - -The following are known deployments of OTP in a government- or agency-sponsored production capacity: - -* **Norway (nationwide)** Since November 2017, the national integrated ticketing agency Entur has - prodvided a [national journey planner](https://en-tur.no/) which consumes schedule data in the EU - standard NeTEx format with SIRI real-time updates. Entur has contributed greatly to the OTP2 effort - and primarily uses OTP2 in production, handling peak loads in excess of 20 requests per second. - Most regional agencies in Norway, like **Ruter, Oslo area** uses OTP as a service provided by Entur. -* **Finland (nationwide)** The [Helsinki Regional Transport Authority](https://www.reittiopas.fi/), - the [Finnish Transport Agency](https://opas.matka.fi/), and - other [Finnish cities](https://waltti.fi/?lang=en) have collaborated to - create [Digitransit](https://digitransit.fi/en/), providing OTP-based trip planners, APIs, open - data, Docker containers and open source code. Each member organisation runs its own instance of a - shared codebase and deployment environment. Their source code is - available [on Github](https://github.com/HSLdevcom/), including - a [new custom UI](https://github.com/HSLdevcom/digitransit-ui). This system also has a strong - real-time component. -* **Finland Intercity** The Finnish intercity coach - service [Matkahuolto](https://en.wikipedia.org/wiki/Matkahuolto) - has [developed a trip planner in partnership with Kyyti](https://www.kyyti.com/matkahuoltos-new-app-brings-real-travel-chains-within-the-reach-of-citizens-in-addition-to-coach-travel-hsl-tickets-are-also-available/). -* **Skåne, Sweden**, the JourneyPlanner and mobile app for the regional transit agency [Skånetrafiken](https://www.skanetrafiken.se/) - uses OTP2 with the nordic profile of NeTEx and SIRI for real-time updates. -* [**Northern Colorado**](https://discover.rideno.co/) -* [**Philadelphia and surrounding areas**](https://plan.septa.org) -* **Portland, Oregon** TriMet is the agency that originally started the OpenTripPlanner project. - Their [Regional Trip Planner](http://ride.trimet.org) is based on OTP and provides about 40,000 - trip plans on a typical weekday. -* [**New York City**](https://new.mta.info/) -* **New York State** The State Department of - Transportation's [transit trip planner](https://511ny.org/#TransitRegion-1) provides itineraries - for public transit systems throughout the state in a single unified OTP instance. -* **Los Angeles, California** The new [metro.net trip planner](https://www.metro.net/). -* **Atlanta, Georgia** The Metropolitan Atlanta Rapid Transit Authority's ( - MARTA) [trip planner](http://itsmarta.com/planatrip.aspx) and the Atlanta region's transit - information hub [https://atlrides.com/](https://atlrides.com/) both use OTP to power their website trip - planners. -* **Boston, Massachusetts** - The [Massachusetts Bay Transportation Authority trip planner](https://www.mbta.com/trip-planner). -* **Seattle, Washington** The [Sound Transit Trip Planner](https://www.soundtransit.org/tripplanner) - is based on OTP. OTP also powers the trip planning feature of - the [OneBusAway native apps](http://onebusaway.org/) in the Puget Sound region. Technical details - are [here](https://github.com/OneBusAway/onebusaway-android/blob/master/SYSTEM_ARCHITECTURE.md#add-trip-planning-andor-bike-share-optional) - . -* [**Ride Metro Houston**](https://planyourtrip.ridemetro.org/) -* **Tampa, Florida** Hillsoborough Area Regional Transit uses an OpenTripPlanner server to power the - trip planning feature of the [OneBusAway native apps](http://onebusaway.org/) in their region. - Technical details - are [here](https://github.com/OneBusAway/onebusaway-android/blob/master/SYSTEM_ARCHITECTURE.md#add-trip-planning-andor-bike-share-optional) - . -* [**Piemonte Region, Italy**](https://map.muoversinpiemonte.it/#planner) and the [**City of - Torino**](https://www.muoversiatorino.it/) built on OpenTripPlanner - by [5T](http://www.5t.torino.it/). -* [**Valencia, Spain**](http://www.emtvalencia.es/geoportal/?lang=en_otp) from the Municipal - Transport Company of Valencia S.A.U. -* [**Grenoble, France**](http://www.metromobilite.fr/) from SMTC, Grenoble Alpes métropole, l'État - Français, the Rhône-alpes region, the Isère council and the City of Grenoble. -* **Rennes, France** where the STAR network provides an OTP client - for [iOS](https://itunes.apple.com/us/app/starbusmetro/id899970416?mt=8) - , [Android](https://play.google.com/store/apps/details?id=com.bookbeo.starbusmetro), Windows Phone - et Web. -* **Alençon, France** integrated urban and school bus - network [planner from Réunir Alençon](https://altobus.com/mon-itineraire/). -* [**Poznań, Poland**](http://ztm.poznan.pl/#planner) from Urban Transport Authority of Poznań (ZTM - Poznan). -* **Trento Province, Italy** - - [ViaggiaTrento](https://play.google.com/store/apps/details?id=eu.trentorise.smartcampus.viaggiatrento) - and [ViaggiaRovereto](https://play.google.com/store/apps/details?id=eu.trentorise.smartcampus.viaggiarovereto) - were implemented as part of the [SmartCampus Project](http://www.smartcampuslab.it), a research - project founded by [TrentoRise](http://trentorise.eu), [UNITN](http://www.unitn.it), - and [FBK](http://www.fbk.eu). -* **University of South Florida** (Tampa, Florida). The [USF Maps App](https://maps.usf.edu/) is a - responsive web application for that helps university students, staff, and visitors find their way - around the campus using multiple modes of transportation, including the USF Bull Runner campus - shuttle, Share-A-Bull bike share, and pedestrian pathways. - Open-sourced [on Github](https://github.com/CUTR-at-USF/usf-mobullity). -* **Lower Saxony, Germany** The [VBN](https://www.vbn.de/en/) transportation authority offers an [OTP instance](https://www.vbn.de/en/service/developer-information/opendata-and-openservice) as alternative to the [Hafas](https://www.hacon.de/en/portfolio/information-ticketing/#section_8294) passenger information system. -* **Leipzig, Germany** As of summer 2020 [Leipzig Move](https://leipzig-move.de/) has been using - OpenTripPlanner. - -## Independent Production - -The following OTP-based services are presented as production-quality deployments, but are not backed -by an official transportation authority or government. OTP is also known to be used on the back end -of several popular multi-city mobile trip planning applications. - -* **The Netherlands (nationwide)** [Plannerstack Foundation](http://www.plannerstack.org/) provides - national scale trip planning APIs using OTP and other open source trip planners, based - on [OpenOV's extremely detailed open data](http://gtfs.openov.nl/) including minutely real-time - updates for every vehicle in the country. -* [OTP Android](https://play.google.com/store/apps/details?id=edu.usf.cutr.opentripplanner.android) - by CUTR-USF and Vreixo González can find itineraries on many different OTP servers via a service - discovery mechanism. -* [**ViviBus Bologna**](http://www.vivibus.it/) Bologna, Italy. +# OpenTripPlanner Deployments Worldwide + +## Official Production + +The following are known deployments of OTP in a government- or agency-sponsored production capacity: + +* **Norway (nationwide)** Since November 2017, the national integrated ticketing agency Entur has + prodvided a [national journey planner](https://en-tur.no/) which consumes schedule data in the EU + standard NeTEx format with SIRI real-time updates. Entur has contributed greatly to the OTP2 effort + and primarily uses OTP2 in production, handling peak loads in excess of 20 requests per second. + Most regional agencies in Norway, like **Ruter, Oslo area** uses OTP as a service provided by Entur. +* **Finland (nationwide)** The [Helsinki Regional Transport Authority](https://www.reittiopas.fi/), + the [Finnish Transport Agency](https://opas.matka.fi/), and + other [Finnish cities](https://waltti.fi/?lang=en) have collaborated to + create [Digitransit](https://digitransit.fi/en/), providing OTP-based trip planners, APIs, open + data, Docker containers and open source code. Each member organisation runs its own instance of a + shared codebase and deployment environment. Their source code is + available [on Github](https://github.com/HSLdevcom/), including + a [new custom UI](https://github.com/HSLdevcom/digitransit-ui). This system also has a strong + real-time component. +* **Finland Intercity** The Finnish intercity coach + service [Matkahuolto](https://en.wikipedia.org/wiki/Matkahuolto) + has [developed a trip planner in partnership with Kyyti](https://www.kyyti.com/matkahuoltos-new-app-brings-real-travel-chains-within-the-reach-of-citizens-in-addition-to-coach-travel-hsl-tickets-are-also-available/). +* **Skåne, Sweden**, the JourneyPlanner and mobile app for the regional transit agency [Skånetrafiken](https://www.skanetrafiken.se/) + uses OTP2 with the nordic profile of NeTEx and SIRI for real-time updates. +* [**Northern Colorado**](https://discover.rideno.co/) +* [**Philadelphia and surrounding areas**](https://plan.septa.org) +* **Portland, Oregon** TriMet is the agency that originally started the OpenTripPlanner project. + Their [Regional Trip Planner](http://ride.trimet.org) is based on OTP and provides about 40,000 + trip plans on a typical weekday. +* [**New York City**](https://new.mta.info/) +* **New York State** The State Department of + Transportation's [transit trip planner](https://511ny.org/#TransitRegion-1) provides itineraries + for public transit systems throughout the state in a single unified OTP instance. +* **Los Angeles, California** The new [metro.net trip planner](https://www.metro.net/). +* **Atlanta, Georgia** The Metropolitan Atlanta Rapid Transit Authority's ( + MARTA) [trip planner](http://itsmarta.com/planatrip.aspx) and the Atlanta region's transit + information hub [https://atlrides.com/](https://atlrides.com/) both use OTP to power their website trip + planners. +* **Boston, Massachusetts** + The [Massachusetts Bay Transportation Authority trip planner](https://www.mbta.com/trip-planner). +* **Seattle, Washington** The [Sound Transit Trip Planner](https://www.soundtransit.org/tripplanner) + is based on OTP. OTP also powers the trip planning feature of + the [OneBusAway native apps](http://onebusaway.org/) in the Puget Sound region. Technical details + are [here](https://github.com/OneBusAway/onebusaway-android/blob/master/SYSTEM_ARCHITECTURE.md#add-trip-planning-andor-bike-share-optional) + . +* [**Ride Metro Houston**](https://planyourtrip.ridemetro.org/) +* **Tampa, Florida** Hillsoborough Area Regional Transit uses an OpenTripPlanner server to power the + trip planning feature of the [OneBusAway native apps](http://onebusaway.org/) in their region. + Technical details + are [here](https://github.com/OneBusAway/onebusaway-android/blob/master/SYSTEM_ARCHITECTURE.md#add-trip-planning-andor-bike-share-optional) + . +* [**Piemonte Region, Italy**](https://map.muoversinpiemonte.it/#planner) and the [**City of + Torino**](https://www.muoversiatorino.it/) built on OpenTripPlanner + by [5T](http://www.5t.torino.it/). +* [**Valencia, Spain**](http://www.emtvalencia.es/geoportal/?lang=en_otp) from the Municipal + Transport Company of Valencia S.A.U. +* [**Grenoble, France**](http://www.metromobilite.fr/) from SMTC, Grenoble Alpes métropole, l'État + Français, the Rhône-alpes region, the Isère council and the City of Grenoble. +* **Rennes, France** where the STAR network provides an OTP client + for [iOS](https://itunes.apple.com/us/app/starbusmetro/id899970416?mt=8) + , [Android](https://play.google.com/store/apps/details?id=com.bookbeo.starbusmetro), Windows Phone + et Web. +* **Alençon, France** integrated urban and school bus + network [planner from Réunir Alençon](https://altobus.com/mon-itineraire/). +* [**Poznań, Poland**](http://ztm.poznan.pl/#planner) from Urban Transport Authority of Poznań (ZTM + Poznan). +* **Trento Province, Italy** + - [ViaggiaTrento](https://play.google.com/store/apps/details?id=eu.trentorise.smartcampus.viaggiatrento) + and [ViaggiaRovereto](https://play.google.com/store/apps/details?id=eu.trentorise.smartcampus.viaggiarovereto) + were implemented as part of the [SmartCampus Project](http://www.smartcampuslab.it), a research + project founded by [TrentoRise](http://trentorise.eu), [UNITN](http://www.unitn.it), + and [FBK](http://www.fbk.eu). +* **University of South Florida** (Tampa, Florida). The [USF Maps App](https://maps.usf.edu/) is a + responsive web application for that helps university students, staff, and visitors find their way + around the campus using multiple modes of transportation, including the USF Bull Runner campus + shuttle, Share-A-Bull bike share, and pedestrian pathways. + Open-sourced [on Github](https://github.com/CUTR-at-USF/usf-mobullity). +* **Lower Saxony, Germany** The [VBN](https://www.vbn.de/en/) transportation authority offers an [OTP instance](https://www.vbn.de/en/service/developer-information/opendata-and-openservice) as alternative to the [Hafas](https://www.hacon.de/en/portfolio/information-ticketing/#section_8294) passenger information system. +* **Leipzig, Germany** As of summer 2020 [Leipzig Move](https://leipzig-move.de/) has been using + OpenTripPlanner. + +## Independent Production + +The following OTP-based services are presented as production-quality deployments, but are not backed +by an official transportation authority or government. OTP is also known to be used on the back end +of several popular multi-city mobile trip planning applications. + +* **The Netherlands (nationwide)** [Plannerstack Foundation](http://www.plannerstack.org/) provides + national scale trip planning APIs using OTP and other open source trip planners, based + on [OpenOV's extremely detailed open data](http://gtfs.openov.nl/) including minutely real-time + updates for every vehicle in the country. +* [OTP Android](https://play.google.com/store/apps/details?id=edu.usf.cutr.opentripplanner.android) + by CUTR-USF and Vreixo González can find itineraries on many different OTP servers via a service + discovery mechanism. +* [**ViviBus Bologna**](http://www.vivibus.it/) Bologna, Italy. diff --git a/docs/Developers-Guide.md b/doc/user/Developers-Guide.md similarity index 99% rename from docs/Developers-Guide.md rename to doc/user/Developers-Guide.md index 0b9ec011f96..e5ebfdb5e85 100644 --- a/docs/Developers-Guide.md +++ b/doc/user/Developers-Guide.md @@ -219,7 +219,7 @@ compile and test the new code, providing feedback on the stability of the build. ### Changelog workflow -The [changelog file](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/docs/Changelog.md) +The [changelog file](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/doc/user/Changelog.md) is generated from the pull-request(PR) _title_ using the [changelog workflow](https://github.com/opentripplanner/OpenTripPlanner/actions/workflows/automatic-changelog.yml) . The workflow runs after the PR is merged, and it changes, commits and pushes the _Changelog.md_. A diff --git a/docs/Frontends.md b/doc/user/Frontends.md similarity index 100% rename from docs/Frontends.md rename to doc/user/Frontends.md diff --git a/docs/Getting-OTP.md b/doc/user/Getting-OTP.md similarity index 100% rename from docs/Getting-OTP.md rename to doc/user/Getting-OTP.md diff --git a/docs/Governance.md b/doc/user/Governance.md similarity index 100% rename from docs/Governance.md rename to doc/user/Governance.md diff --git a/docs/History.md b/doc/user/History.md similarity index 100% rename from docs/History.md rename to doc/user/History.md diff --git a/docs/In-Station-Navigation.md b/doc/user/In-Station-Navigation.md similarity index 100% rename from docs/In-Station-Navigation.md rename to doc/user/In-Station-Navigation.md diff --git a/docs/IslandPruning.md b/doc/user/IslandPruning.md similarity index 100% rename from docs/IslandPruning.md rename to doc/user/IslandPruning.md diff --git a/docs/Localization.md b/doc/user/Localization.md similarity index 100% rename from docs/Localization.md rename to doc/user/Localization.md diff --git a/docs/Logging.md b/doc/user/Logging.md similarity index 100% rename from docs/Logging.md rename to doc/user/Logging.md diff --git a/docs/Migrating-Configuration.md b/doc/user/Migrating-Configuration.md similarity index 100% rename from docs/Migrating-Configuration.md rename to doc/user/Migrating-Configuration.md diff --git a/docs/Netex-Norway.md b/doc/user/Netex-Norway.md similarity index 100% rename from docs/Netex-Norway.md rename to doc/user/Netex-Norway.md diff --git a/docs/Preparing-OSM.md b/doc/user/Preparing-OSM.md similarity index 100% rename from docs/Preparing-OSM.md rename to doc/user/Preparing-OSM.md diff --git a/docs/Presentations.md b/doc/user/Presentations.md similarity index 100% rename from docs/Presentations.md rename to doc/user/Presentations.md diff --git a/docs/Product-Overview.md b/doc/user/Product-Overview.md similarity index 100% rename from docs/Product-Overview.md rename to doc/user/Product-Overview.md diff --git a/docs/README-DOCS.txt b/doc/user/README-DOCS.txt similarity index 100% rename from docs/README-DOCS.txt rename to doc/user/README-DOCS.txt diff --git a/docs/ReleaseChecklist.md b/doc/user/ReleaseChecklist.md similarity index 96% rename from docs/ReleaseChecklist.md rename to doc/user/ReleaseChecklist.md index 0f7c0667762..c67849bc538 100644 --- a/docs/ReleaseChecklist.md +++ b/doc/user/ReleaseChecklist.md @@ -14,8 +14,8 @@ manually is more tedious, but keeps eyes on each step and is less prone to failu * Check all links and references to the release and update to the target release version. Search all files for with a regular expression: `2\.[012]\.0` and replace if appropriate with the new version. - * In `docs/index.md` replace what is the latest version and add a new line for the previous one -* Update `docs/Changelog.md` + * In `doc/user/index.md` replace what is the latest version and add a new line for the previous one +* Update `doc/user/Changelog.md` * Lines should have been added or updated as each pull request was merged * If you suspect any changes are not reflected in the Changelog, review the commit log and add any missing items @@ -78,9 +78,9 @@ manually is more tedious, but keeps eyes on each step and is less prone to failu * `git merge master` * `git push` * Set up next development iteration - * Add a new section header to `docs/Changelog.md` like `x.y+1.0-SNAPSHOT (in progress)` + * Add a new section header to `doc/user/Changelog.md` like `x.y+1.0-SNAPSHOT (in progress)` * Edit minor version in `pom.xml` to `x.y+1.0-SNAPSHOT` - * `git add pom.xml docs/Changelog.md` + * `git add pom.xml doc/user/Changelog.md` * `git commit -m "Prepare next development iteration x.y+1.0-SNAPSHOT"` * `git push` * Send a message in Gitter and email the OTP users mailing lists diff --git a/docs/Roadmap.md b/doc/user/Roadmap.md similarity index 100% rename from docs/Roadmap.md rename to doc/user/Roadmap.md diff --git a/docs/RouteRequest.md b/doc/user/RouteRequest.md similarity index 100% rename from docs/RouteRequest.md rename to doc/user/RouteRequest.md diff --git a/docs/RouterConfiguration.md b/doc/user/RouterConfiguration.md similarity index 100% rename from docs/RouterConfiguration.md rename to doc/user/RouterConfiguration.md diff --git a/docs/RoutingModes.md b/doc/user/RoutingModes.md similarity index 100% rename from docs/RoutingModes.md rename to doc/user/RoutingModes.md diff --git a/docs/SandboxExtension.md b/doc/user/SandboxExtension.md similarity index 97% rename from docs/SandboxExtension.md rename to doc/user/SandboxExtension.md index 0d05518fd56..70dec6f678d 100644 --- a/docs/SandboxExtension.md +++ b/doc/user/SandboxExtension.md @@ -30,7 +30,7 @@ added in the test directory: `src/ext-test` - To integrate the new feature into OTP you may have to create new extension points in the main/core code. Changes to the core OTP are subject to normal a review process. -- Create a readme file (`docs/sandbox/.md` package including: +- Create a readme file (`doc/user/sandbox/.md` package including: - Extension Name - Contact info - Change log diff --git a/docs/StopAreas.md b/doc/user/StopAreas.md similarity index 100% rename from docs/StopAreas.md rename to doc/user/StopAreas.md diff --git a/docs/System-Requirements.md b/doc/user/System-Requirements.md similarity index 100% rename from docs/System-Requirements.md rename to doc/user/System-Requirements.md diff --git a/docs/Troubleshooting-Routing.md b/doc/user/Troubleshooting-Routing.md similarity index 100% rename from docs/Troubleshooting-Routing.md rename to doc/user/Troubleshooting-Routing.md diff --git a/docs/UpdaterConfig.md b/doc/user/UpdaterConfig.md similarity index 100% rename from docs/UpdaterConfig.md rename to doc/user/UpdaterConfig.md diff --git a/docs/Version-Comparison.md b/doc/user/Version-Comparison.md similarity index 100% rename from docs/Version-Comparison.md rename to doc/user/Version-Comparison.md diff --git a/docs/Visual-Identity.md b/doc/user/Visual-Identity.md similarity index 100% rename from docs/Visual-Identity.md rename to doc/user/Visual-Identity.md diff --git a/docs/apis/Apis.md b/doc/user/apis/Apis.md similarity index 100% rename from docs/apis/Apis.md rename to doc/user/apis/Apis.md diff --git a/docs/apis/GTFS-GraphQL-API.md b/doc/user/apis/GTFS-GraphQL-API.md similarity index 100% rename from docs/apis/GTFS-GraphQL-API.md rename to doc/user/apis/GTFS-GraphQL-API.md diff --git a/docs/apis/GraphQL-Tutorial.md b/doc/user/apis/GraphQL-Tutorial.md similarity index 100% rename from docs/apis/GraphQL-Tutorial.md rename to doc/user/apis/GraphQL-Tutorial.md diff --git a/docs/apis/TransmodelApi.md b/doc/user/apis/TransmodelApi.md similarity index 100% rename from docs/apis/TransmodelApi.md rename to doc/user/apis/TransmodelApi.md diff --git a/docs/examples/Readme.md b/doc/user/examples/Readme.md similarity index 100% rename from docs/examples/Readme.md rename to doc/user/examples/Readme.md diff --git a/docs/examples/entur/Readme.md b/doc/user/examples/entur/Readme.md similarity index 100% rename from docs/examples/entur/Readme.md rename to doc/user/examples/entur/Readme.md diff --git a/docs/examples/entur/build-config.json b/doc/user/examples/entur/build-config.json similarity index 100% rename from docs/examples/entur/build-config.json rename to doc/user/examples/entur/build-config.json diff --git a/docs/examples/entur/otp-config.json b/doc/user/examples/entur/otp-config.json similarity index 100% rename from docs/examples/entur/otp-config.json rename to doc/user/examples/entur/otp-config.json diff --git a/docs/examples/entur/router-config.json b/doc/user/examples/entur/router-config.json similarity index 100% rename from docs/examples/entur/router-config.json rename to doc/user/examples/entur/router-config.json diff --git a/docs/examples/ibi/atlanta/build-config.json b/doc/user/examples/ibi/atlanta/build-config.json similarity index 100% rename from docs/examples/ibi/atlanta/build-config.json rename to doc/user/examples/ibi/atlanta/build-config.json diff --git a/docs/examples/ibi/atlanta/otp-config.json b/doc/user/examples/ibi/atlanta/otp-config.json similarity index 100% rename from docs/examples/ibi/atlanta/otp-config.json rename to doc/user/examples/ibi/atlanta/otp-config.json diff --git a/docs/examples/ibi/atlanta/router-config.json b/doc/user/examples/ibi/atlanta/router-config.json similarity index 100% rename from docs/examples/ibi/atlanta/router-config.json rename to doc/user/examples/ibi/atlanta/router-config.json diff --git a/docs/examples/ibi/houston/build-config.json b/doc/user/examples/ibi/houston/build-config.json similarity index 100% rename from docs/examples/ibi/houston/build-config.json rename to doc/user/examples/ibi/houston/build-config.json diff --git a/docs/examples/ibi/portland/build-config.json b/doc/user/examples/ibi/portland/build-config.json similarity index 100% rename from docs/examples/ibi/portland/build-config.json rename to doc/user/examples/ibi/portland/build-config.json diff --git a/docs/examples/ibi/portland/otp-config.json b/doc/user/examples/ibi/portland/otp-config.json similarity index 100% rename from docs/examples/ibi/portland/otp-config.json rename to doc/user/examples/ibi/portland/otp-config.json diff --git a/docs/examples/ibi/portland/router-config.json b/doc/user/examples/ibi/portland/router-config.json similarity index 100% rename from docs/examples/ibi/portland/router-config.json rename to doc/user/examples/ibi/portland/router-config.json diff --git a/docs/examples/ibi/seattle/build-config.json b/doc/user/examples/ibi/seattle/build-config.json similarity index 100% rename from docs/examples/ibi/seattle/build-config.json rename to doc/user/examples/ibi/seattle/build-config.json diff --git a/docs/examples/ibi/seattle/router-config.json b/doc/user/examples/ibi/seattle/router-config.json similarity index 100% rename from docs/examples/ibi/seattle/router-config.json rename to doc/user/examples/ibi/seattle/router-config.json diff --git a/docs/examples/ibi/septa/router-config.json b/doc/user/examples/ibi/septa/router-config.json similarity index 100% rename from docs/examples/ibi/septa/router-config.json rename to doc/user/examples/ibi/septa/router-config.json diff --git a/docs/examples/skanetrafiken/Readme.md b/doc/user/examples/skanetrafiken/Readme.md similarity index 100% rename from docs/examples/skanetrafiken/Readme.md rename to doc/user/examples/skanetrafiken/Readme.md diff --git a/docs/examples/skanetrafiken/build-config.json b/doc/user/examples/skanetrafiken/build-config.json similarity index 100% rename from docs/examples/skanetrafiken/build-config.json rename to doc/user/examples/skanetrafiken/build-config.json diff --git a/docs/examples/skanetrafiken/oresund.json b/doc/user/examples/skanetrafiken/oresund.json similarity index 100% rename from docs/examples/skanetrafiken/oresund.json rename to doc/user/examples/skanetrafiken/oresund.json diff --git a/docs/examples/skanetrafiken/router-config.json b/doc/user/examples/skanetrafiken/router-config.json similarity index 100% rename from docs/examples/skanetrafiken/router-config.json rename to doc/user/examples/skanetrafiken/router-config.json diff --git a/docs/github_issue_linker.py b/doc/user/github_issue_linker.py similarity index 100% rename from docs/github_issue_linker.py rename to doc/user/github_issue_linker.py diff --git a/docs/images/ExternalToolDialog.png b/doc/user/images/ExternalToolDialog.png similarity index 100% rename from docs/images/ExternalToolDialog.png rename to doc/user/images/ExternalToolDialog.png diff --git a/docs/images/ServiceModelOverview.png b/doc/user/images/ServiceModelOverview.png similarity index 100% rename from docs/images/ServiceModelOverview.png rename to doc/user/images/ServiceModelOverview.png diff --git a/docs/images/TransitTimeLine.svg b/doc/user/images/TransitTimeLine.svg similarity index 100% rename from docs/images/TransitTimeLine.svg rename to doc/user/images/TransitTimeLine.svg diff --git a/docs/images/badprojection.png b/doc/user/images/badprojection.png similarity index 100% rename from docs/images/badprojection.png rename to doc/user/images/badprojection.png diff --git a/docs/images/bicycle-safety-report.png b/doc/user/images/bicycle-safety-report.png similarity index 100% rename from docs/images/bicycle-safety-report.png rename to doc/user/images/bicycle-safety-report.png diff --git a/docs/images/boarding-schwabstrasse.png b/doc/user/images/boarding-schwabstrasse.png similarity index 100% rename from docs/images/boarding-schwabstrasse.png rename to doc/user/images/boarding-schwabstrasse.png diff --git a/docs/images/buckhead-station.png b/doc/user/images/buckhead-station.png similarity index 100% rename from docs/images/buckhead-station.png rename to doc/user/images/buckhead-station.png diff --git a/docs/images/cli-flow.svg b/doc/user/images/cli-flow.svg similarity index 100% rename from docs/images/cli-flow.svg rename to doc/user/images/cli-flow.svg diff --git a/docs/images/example-isochrone.png b/doc/user/images/example-isochrone.png similarity index 100% rename from docs/images/example-isochrone.png rename to doc/user/images/example-isochrone.png diff --git a/docs/images/exiting-oesterfeld.png b/doc/user/images/exiting-oesterfeld.png similarity index 100% rename from docs/images/exiting-oesterfeld.png rename to doc/user/images/exiting-oesterfeld.png diff --git a/docs/images/graphiql-autocomplete.png b/doc/user/images/graphiql-autocomplete.png similarity index 100% rename from docs/images/graphiql-autocomplete.png rename to doc/user/images/graphiql-autocomplete.png diff --git a/docs/images/graphiql-documentation.png b/doc/user/images/graphiql-documentation.png similarity index 100% rename from docs/images/graphiql-documentation.png rename to doc/user/images/graphiql-documentation.png diff --git a/docs/images/graphiql.png b/doc/user/images/graphiql.png similarity index 100% rename from docs/images/graphiql.png rename to doc/user/images/graphiql.png diff --git a/docs/images/nothruisland.png b/doc/user/images/nothruisland.png similarity index 100% rename from docs/images/nothruisland.png rename to doc/user/images/nothruisland.png diff --git a/docs/images/osmislands.png b/doc/user/images/osmislands.png similarity index 100% rename from docs/images/osmislands.png rename to doc/user/images/osmislands.png diff --git a/docs/images/otp-logo.svg b/doc/user/images/otp-logo.svg similarity index 87% rename from docs/images/otp-logo.svg rename to doc/user/images/otp-logo.svg index 1ed23d0be8e..6e32af842a6 100644 --- a/docs/images/otp-logo.svg +++ b/doc/user/images/otp-logo.svg @@ -1,7 +1,8 @@ - + *
  • The configuration type table
    • *
  • The list of OTP features
    • * - * This test fails if the document have changed. This make sure that this test fails in the - * CI pipeline if config file changes is not committed. Manually inspect the changes in the + * This test fails if the document has changed. This makes sure that this test fails in the + * CI pipeline if config file changes are not committed. Manually inspect the changes in the * configuration, commit the configuration document, and run test again to pass. */ @Test diff --git a/src/test/java/org/opentripplanner/generate/doc/GraphQLTutorialDocTest.java b/src/test/java/org/opentripplanner/generate/doc/GraphQLTutorialDocTest.java index 3597844a027..83e607449eb 100644 --- a/src/test/java/org/opentripplanner/generate/doc/GraphQLTutorialDocTest.java +++ b/src/test/java/org/opentripplanner/generate/doc/GraphQLTutorialDocTest.java @@ -25,7 +25,7 @@ public class GraphQLTutorialDocTest { private static final File OUT_FILE = new File(DOCS_ROOT + "/apis", "GraphQL-Tutorial.md"); /** - * NOTE! This test updates the {@code docs/GraphQlTutorial.md} document based on the latest + * NOTE! This test updates the {@code doc/user/GraphQlTutorial.md} document based on the latest * version of the code. * This test fails if the document have changed. This make sure that this test fails in the * CI pipeline if config file changes is not committed. Manually inspect the changes in the diff --git a/src/test/java/org/opentripplanner/generate/doc/RouteRequestDocTest.java b/src/test/java/org/opentripplanner/generate/doc/RouteRequestDocTest.java index 76642db3e5a..0d4f0e9cff1 100644 --- a/src/test/java/org/opentripplanner/generate/doc/RouteRequestDocTest.java +++ b/src/test/java/org/opentripplanner/generate/doc/RouteRequestDocTest.java @@ -34,7 +34,7 @@ public class RouteRequestDocTest { .build(); /** - * NOTE! This test updates the {@code docs/RouteRequest.md} document based on the latest + * NOTE! This test updates the {@code doc/user/RouteRequest.md} document based on the latest * version of the code. The following is auto generated: *
      *
    • The configuration type table
      • diff --git a/src/test/java/org/opentripplanner/generate/doc/RouterConfigurationDocTest.java b/src/test/java/org/opentripplanner/generate/doc/RouterConfigurationDocTest.java index 90cdd9de975..2ec95c3cd05 100644 --- a/src/test/java/org/opentripplanner/generate/doc/RouterConfigurationDocTest.java +++ b/src/test/java/org/opentripplanner/generate/doc/RouterConfigurationDocTest.java @@ -40,7 +40,7 @@ public class RouterConfigurationDocTest { .build(); /** - * NOTE! This test updates the {@code docs/Configuration.md} document based on the latest + * NOTE! This test updates the {@code doc/user/Configuration.md} document based on the latest * version of the code. The following is auto generated: *
        *
      • The configuration type table
        • diff --git a/src/test/java/org/opentripplanner/generate/doc/SiriAzureConfigDocTest.java b/src/test/java/org/opentripplanner/generate/doc/SiriAzureConfigDocTest.java index 374ac2b4bbb..c910ee3bf7b 100644 --- a/src/test/java/org/opentripplanner/generate/doc/SiriAzureConfigDocTest.java +++ b/src/test/java/org/opentripplanner/generate/doc/SiriAzureConfigDocTest.java @@ -37,7 +37,7 @@ public class SiriAzureConfigDocTest { public static final ObjectMapper mapper = new ObjectMapper(); /** - * NOTE! This test updates the {@code docs/sandbox/SiriUpdater.md} document based on the latest + * NOTE! This test updates the {@code doc/user/sandbox/SiriUpdater.md} document based on the latest * version of the code. */ @Test diff --git a/src/test/java/org/opentripplanner/generate/doc/SiriConfigDocTest.java b/src/test/java/org/opentripplanner/generate/doc/SiriConfigDocTest.java index 2474f37c402..46d829cc4c3 100644 --- a/src/test/java/org/opentripplanner/generate/doc/SiriConfigDocTest.java +++ b/src/test/java/org/opentripplanner/generate/doc/SiriConfigDocTest.java @@ -34,7 +34,7 @@ public class SiriConfigDocTest { public static final ObjectMapper mapper = new ObjectMapper(); /** - * NOTE! This test updates the {@code docs/sandbox/SiriUpdater.md} document based on the latest + * NOTE! This test updates the {@code doc/user/sandbox/SiriUpdater.md} document based on the latest * version of the code. */ @Test diff --git a/src/test/java/org/opentripplanner/generate/doc/SiriGooglePubSubConfigDocTest.java b/src/test/java/org/opentripplanner/generate/doc/SiriGooglePubSubConfigDocTest.java index f5aa3e130ed..342344363b3 100644 --- a/src/test/java/org/opentripplanner/generate/doc/SiriGooglePubSubConfigDocTest.java +++ b/src/test/java/org/opentripplanner/generate/doc/SiriGooglePubSubConfigDocTest.java @@ -40,7 +40,7 @@ public class SiriGooglePubSubConfigDocTest { public static final ObjectMapper mapper = new ObjectMapper(); /** - * NOTE! This test updates the {@code docs/sandbox/SiriGooglePubSubUpdater.md} document based on the latest + * NOTE! This test updates the {@code doc/user/sandbox/SiriGooglePubSubUpdater.md} document based on the latest * version of the code. */ @Test diff --git a/src/test/java/org/opentripplanner/generate/doc/UpdaterConfigDocTest.java b/src/test/java/org/opentripplanner/generate/doc/UpdaterConfigDocTest.java index 264d0d6850a..75d6cb6fe5a 100644 --- a/src/test/java/org/opentripplanner/generate/doc/UpdaterConfigDocTest.java +++ b/src/test/java/org/opentripplanner/generate/doc/UpdaterConfigDocTest.java @@ -41,7 +41,7 @@ public class UpdaterConfigDocTest { public static final ObjectMapper mapper = new ObjectMapper(); /** - * NOTE! This test updates the {@code docs/Configuration.md} document based on the latest + * NOTE! This test updates the {@code doc/user/Configuration.md} document based on the latest * version of the code. The following is auto generated: *
          *
        • The configuration type table
          • diff --git a/src/test/java/org/opentripplanner/generate/doc/framework/DocsTestConstants.java b/src/test/java/org/opentripplanner/generate/doc/framework/DocsTestConstants.java index d7a67a3590b..3f9f30c30b1 100644 --- a/src/test/java/org/opentripplanner/generate/doc/framework/DocsTestConstants.java +++ b/src/test/java/org/opentripplanner/generate/doc/framework/DocsTestConstants.java @@ -10,7 +10,7 @@ public interface DocsTestConstants { Logger LOG = LoggerFactory.getLogger(DocsTestConstants.class); File TEMPLATE_ROOT = new File("doc-templates"); - File DOCS_ROOT = new File("docs"); + File DOCS_ROOT = new File("doc/user"); /** * This method return {@code true} if the /docs directory is available. If not, a warning is @@ -25,7 +25,7 @@ static boolean docsExistOrWarn() { """ SKIP TEST - '/docs' NOT FOUND - The docs/doc-templates directory might not be available if you run the tests outside the + The doc/templates directory might not be available if you run the tests outside the root of the projects. This may happen if the project root is not the working directory, if you run tests using jar files or in a Maven multi-module project. diff --git a/src/test/java/org/opentripplanner/standalone/config/ExampleConfigTest.java b/src/test/java/org/opentripplanner/standalone/config/ExampleConfigTest.java index b250126c019..12b8749c1fe 100644 --- a/src/test/java/org/opentripplanner/standalone/config/ExampleConfigTest.java +++ b/src/test/java/org/opentripplanner/standalone/config/ExampleConfigTest.java @@ -22,7 +22,7 @@ @GeneratesDocumentation public class ExampleConfigTest { - @FilePatternSource(pattern = "docs/examples/**/" + ROUTER_CONFIG_FILENAME) + @FilePatternSource(pattern = "doc/user/examples/**/" + ROUTER_CONFIG_FILENAME) @ParameterizedTest(name = "Check validity of {0}") void routerConfig(Path filename) { testConfig(filename, a -> new RouterConfig(a, true)); @@ -30,7 +30,8 @@ void routerConfig(Path filename) { @FilePatternSource( pattern = { - "docs/examples/**/" + BUILD_CONFIG_FILENAME, "test/performance/**/" + BUILD_CONFIG_FILENAME, + "doc/user/examples/**/" + BUILD_CONFIG_FILENAME, + "test/performance/**/" + BUILD_CONFIG_FILENAME, } ) @ParameterizedTest(name = "Check validity of {0}") @@ -45,7 +46,9 @@ void speedTestConfig(Path filename) { } @FilePatternSource( - pattern = { "test/performance/**/otp-config.json", "docs/examples/**/" + OTP_CONFIG_FILENAME } + pattern = { + "test/performance/**/otp-config.json", "doc/user/examples/**/" + OTP_CONFIG_FILENAME, + } ) @ParameterizedTest(name = "Check validity of {0}") void otpConfig(Path filename) { diff --git a/src/test/java/org/opentripplanner/test/support/FilePatternArgumentsProvider.java b/src/test/java/org/opentripplanner/test/support/FilePatternArgumentsProvider.java index 35869a9094e..c084a81a73f 100644 --- a/src/test/java/org/opentripplanner/test/support/FilePatternArgumentsProvider.java +++ b/src/test/java/org/opentripplanner/test/support/FilePatternArgumentsProvider.java @@ -19,7 +19,7 @@ /** * This annotation processor allows you to provide a file pattern like - * "docs/examples/**\/build-config.json" as the input for a JUnit + * "doc/user/examples/**\/build-config.json" as the input for a JUnit * {@link org.junit.jupiter.params.ParameterizedTest}. *

          * Check the usages of {@link FilePatternSource} to see examples for how to use. From eb5bbae55910c2bb8b733086ddf2f86ef9c62c0a Mon Sep 17 00:00:00 2001 From: Thomas Gran Date: Wed, 24 Jul 2024 15:45:54 +0200 Subject: [PATCH 17/21] Move /doc-templates to /doc/templates --- {doc-templates => doc/templates}/BuildConfiguration.md | 2 +- {doc-templates => doc/templates}/Configuration.md | 2 +- {doc-templates => doc/templates}/Emissions.md | 0 {doc-templates => doc/templates}/Flex.md | 0 {doc-templates => doc/templates}/GraphQL-Tutorial.md | 2 +- {doc-templates => doc/templates}/RideHailing.md | 0 {doc-templates => doc/templates}/RouteRequest.md | 2 +- {doc-templates => doc/templates}/RouterConfiguration.md | 2 +- {doc-templates => doc/templates}/RoutingModes.md | 0 {doc-templates => doc/templates}/StopConsolidation.md | 2 +- {doc-templates => doc/templates}/UpdaterConfig.md | 2 +- {doc-templates => doc/templates}/VehicleParking.md | 0 .../templates}/sandbox/MapboxVectorTilesApi.md | 0 .../templates}/sandbox/VehicleRentalServiceDirectory.md | 0 .../templates}/sandbox/siri/SiriAzureUpdater.md | 0 .../templates}/sandbox/siri/SiriGooglePubSubUpdater.md | 0 .../templates}/sandbox/siri/SiriUpdater.md | 0 doc/user/BuildConfiguration.md | 2 +- doc/user/Configuration.md | 2 +- doc/user/RouteRequest.md | 2 +- doc/user/RouterConfiguration.md | 2 +- doc/user/UpdaterConfig.md | 2 +- doc/user/apis/GraphQL-Tutorial.md | 2 +- doc/user/sandbox/StopConsolidation.md | 2 +- .../ext/vectortiles/VectorTilesConfigDocTest.java | 8 ++++---- .../VehicleRentalServiceDirectoryConfigDocTest.java | 8 ++++---- .../generate/doc/BuildConfigurationDocTest.java | 8 ++++---- .../generate/doc/ConfigurationDocTest.java | 8 ++++---- .../generate/doc/EmissionsConfigurationDocTest.java | 8 ++++---- .../generate/doc/FlexConfigurationDocTest.java | 8 ++++---- .../generate/doc/GraphQLTutorialDocTest.java | 8 ++++---- .../opentripplanner/generate/doc/RideHailingDocTest.java | 8 ++++---- .../opentripplanner/generate/doc/RouteRequestDocTest.java | 8 ++++---- .../generate/doc/RouterConfigurationDocTest.java | 8 ++++---- .../opentripplanner/generate/doc/RoutingModeDocTest.java | 8 ++++---- .../generate/doc/SiriAzureConfigDocTest.java | 8 ++++---- .../opentripplanner/generate/doc/SiriConfigDocTest.java | 8 ++++---- .../generate/doc/SiriGooglePubSubConfigDocTest.java | 8 ++++---- .../generate/doc/StopConsolidationDocTest.java | 8 ++++---- .../generate/doc/UpdaterConfigDocTest.java | 8 ++++---- .../generate/doc/VehicleParkingDocTest.java | 8 ++++---- .../generate/doc/framework/DocsTestConstants.java | 7 ++++--- 42 files changed, 86 insertions(+), 85 deletions(-) rename {doc-templates => doc/templates}/BuildConfiguration.md (99%) rename {doc-templates => doc/templates}/Configuration.md (99%) rename {doc-templates => doc/templates}/Emissions.md (100%) rename {doc-templates => doc/templates}/Flex.md (100%) rename {doc-templates => doc/templates}/GraphQL-Tutorial.md (97%) rename {doc-templates => doc/templates}/RideHailing.md (100%) rename {doc-templates => doc/templates}/RouteRequest.md (92%) rename {doc-templates => doc/templates}/RouterConfiguration.md (96%) rename {doc-templates => doc/templates}/RoutingModes.md (100%) rename {doc-templates => doc/templates}/StopConsolidation.md (97%) rename {doc-templates => doc/templates}/UpdaterConfig.md (98%) rename {doc-templates => doc/templates}/VehicleParking.md (100%) rename {doc-templates => doc/templates}/sandbox/MapboxVectorTilesApi.md (100%) rename {doc-templates => doc/templates}/sandbox/VehicleRentalServiceDirectory.md (100%) rename {doc-templates => doc/templates}/sandbox/siri/SiriAzureUpdater.md (100%) rename {doc-templates => doc/templates}/sandbox/siri/SiriGooglePubSubUpdater.md (100%) rename {doc-templates => doc/templates}/sandbox/siri/SiriUpdater.md (100%) diff --git a/doc-templates/BuildConfiguration.md b/doc/templates/BuildConfiguration.md similarity index 99% rename from doc-templates/BuildConfiguration.md rename to doc/templates/BuildConfiguration.md index 43a29e1fb79..7e768e30eb1 100644 --- a/doc-templates/BuildConfiguration.md +++ b/doc/templates/BuildConfiguration.md @@ -1,7 +1,7 @@ diff --git a/doc-templates/Configuration.md b/doc/templates/Configuration.md similarity index 99% rename from doc-templates/Configuration.md rename to doc/templates/Configuration.md index e06adc46dc5..0ef96b8d4fa 100644 --- a/doc-templates/Configuration.md +++ b/doc/templates/Configuration.md @@ -1,7 +1,7 @@ diff --git a/doc-templates/Emissions.md b/doc/templates/Emissions.md similarity index 100% rename from doc-templates/Emissions.md rename to doc/templates/Emissions.md diff --git a/doc-templates/Flex.md b/doc/templates/Flex.md similarity index 100% rename from doc-templates/Flex.md rename to doc/templates/Flex.md diff --git a/doc-templates/GraphQL-Tutorial.md b/doc/templates/GraphQL-Tutorial.md similarity index 97% rename from doc-templates/GraphQL-Tutorial.md rename to doc/templates/GraphQL-Tutorial.md index 51f0ef7880a..11a2e304119 100644 --- a/doc-templates/GraphQL-Tutorial.md +++ b/doc/templates/GraphQL-Tutorial.md @@ -1,7 +1,7 @@ diff --git a/doc-templates/RideHailing.md b/doc/templates/RideHailing.md similarity index 100% rename from doc-templates/RideHailing.md rename to doc/templates/RideHailing.md diff --git a/doc-templates/RouteRequest.md b/doc/templates/RouteRequest.md similarity index 92% rename from doc-templates/RouteRequest.md rename to doc/templates/RouteRequest.md index 4abfdec71e2..a452e1d1480 100644 --- a/doc-templates/RouteRequest.md +++ b/doc/templates/RouteRequest.md @@ -1,7 +1,7 @@ diff --git a/doc-templates/RouterConfiguration.md b/doc/templates/RouterConfiguration.md similarity index 96% rename from doc-templates/RouterConfiguration.md rename to doc/templates/RouterConfiguration.md index f181bf5db93..b6c6ccf9c4b 100644 --- a/doc-templates/RouterConfiguration.md +++ b/doc/templates/RouterConfiguration.md @@ -1,7 +1,7 @@ diff --git a/doc-templates/RoutingModes.md b/doc/templates/RoutingModes.md similarity index 100% rename from doc-templates/RoutingModes.md rename to doc/templates/RoutingModes.md diff --git a/doc-templates/StopConsolidation.md b/doc/templates/StopConsolidation.md similarity index 97% rename from doc-templates/StopConsolidation.md rename to doc/templates/StopConsolidation.md index c92cab6afe1..6817ee47d4c 100644 --- a/doc-templates/StopConsolidation.md +++ b/doc/templates/StopConsolidation.md @@ -1,7 +1,7 @@ # Stop consolidation diff --git a/doc-templates/UpdaterConfig.md b/doc/templates/UpdaterConfig.md similarity index 98% rename from doc-templates/UpdaterConfig.md rename to doc/templates/UpdaterConfig.md index f16d28f570c..440cd96f733 100644 --- a/doc-templates/UpdaterConfig.md +++ b/doc/templates/UpdaterConfig.md @@ -1,7 +1,7 @@ diff --git a/doc-templates/VehicleParking.md b/doc/templates/VehicleParking.md similarity index 100% rename from doc-templates/VehicleParking.md rename to doc/templates/VehicleParking.md diff --git a/doc-templates/sandbox/MapboxVectorTilesApi.md b/doc/templates/sandbox/MapboxVectorTilesApi.md similarity index 100% rename from doc-templates/sandbox/MapboxVectorTilesApi.md rename to doc/templates/sandbox/MapboxVectorTilesApi.md diff --git a/doc-templates/sandbox/VehicleRentalServiceDirectory.md b/doc/templates/sandbox/VehicleRentalServiceDirectory.md similarity index 100% rename from doc-templates/sandbox/VehicleRentalServiceDirectory.md rename to doc/templates/sandbox/VehicleRentalServiceDirectory.md diff --git a/doc-templates/sandbox/siri/SiriAzureUpdater.md b/doc/templates/sandbox/siri/SiriAzureUpdater.md similarity index 100% rename from doc-templates/sandbox/siri/SiriAzureUpdater.md rename to doc/templates/sandbox/siri/SiriAzureUpdater.md diff --git a/doc-templates/sandbox/siri/SiriGooglePubSubUpdater.md b/doc/templates/sandbox/siri/SiriGooglePubSubUpdater.md similarity index 100% rename from doc-templates/sandbox/siri/SiriGooglePubSubUpdater.md rename to doc/templates/sandbox/siri/SiriGooglePubSubUpdater.md diff --git a/doc-templates/sandbox/siri/SiriUpdater.md b/doc/templates/sandbox/siri/SiriUpdater.md similarity index 100% rename from doc-templates/sandbox/siri/SiriUpdater.md rename to doc/templates/sandbox/siri/SiriUpdater.md diff --git a/doc/user/BuildConfiguration.md b/doc/user/BuildConfiguration.md index cefd8d2cf2f..561963f1a1f 100644 --- a/doc/user/BuildConfiguration.md +++ b/doc/user/BuildConfiguration.md @@ -1,7 +1,7 @@ diff --git a/doc/user/Configuration.md b/doc/user/Configuration.md index 05611e23628..e7d30fbaae5 100644 --- a/doc/user/Configuration.md +++ b/doc/user/Configuration.md @@ -1,7 +1,7 @@ diff --git a/doc/user/RouteRequest.md b/doc/user/RouteRequest.md index 14d937eeb63..28c5e288971 100644 --- a/doc/user/RouteRequest.md +++ b/doc/user/RouteRequest.md @@ -1,7 +1,7 @@ diff --git a/doc/user/RouterConfiguration.md b/doc/user/RouterConfiguration.md index a3042e7b91f..53aa82f66f2 100644 --- a/doc/user/RouterConfiguration.md +++ b/doc/user/RouterConfiguration.md @@ -1,7 +1,7 @@ diff --git a/doc/user/UpdaterConfig.md b/doc/user/UpdaterConfig.md index ebe0acf94b4..f3a0d982e68 100644 --- a/doc/user/UpdaterConfig.md +++ b/doc/user/UpdaterConfig.md @@ -1,7 +1,7 @@ diff --git a/doc/user/apis/GraphQL-Tutorial.md b/doc/user/apis/GraphQL-Tutorial.md index bfc87813f1d..d65fbc144ba 100644 --- a/doc/user/apis/GraphQL-Tutorial.md +++ b/doc/user/apis/GraphQL-Tutorial.md @@ -1,7 +1,7 @@ diff --git a/doc/user/sandbox/StopConsolidation.md b/doc/user/sandbox/StopConsolidation.md index 750a873b547..b36429b1f60 100644 --- a/doc/user/sandbox/StopConsolidation.md +++ b/doc/user/sandbox/StopConsolidation.md @@ -1,7 +1,7 @@ # Stop consolidation diff --git a/src/ext-test/java/org/opentripplanner/ext/vectortiles/VectorTilesConfigDocTest.java b/src/ext-test/java/org/opentripplanner/ext/vectortiles/VectorTilesConfigDocTest.java index 233e3fa3737..51e1738ff6c 100644 --- a/src/ext-test/java/org/opentripplanner/ext/vectortiles/VectorTilesConfigDocTest.java +++ b/src/ext-test/java/org/opentripplanner/ext/vectortiles/VectorTilesConfigDocTest.java @@ -4,8 +4,8 @@ import static org.opentripplanner.framework.io.FileUtils.readFile; import static org.opentripplanner.framework.io.FileUtils.writeFile; import static org.opentripplanner.framework.text.MarkdownFormatter.HEADER_4; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.DOCS_ROOT; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_ROOT; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_PATH; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.USER_DOC_PATH; import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceSection; import static org.opentripplanner.standalone.config.framework.json.JsonSupport.jsonNodeFromPath; @@ -24,8 +24,8 @@ public class VectorTilesConfigDocTest { private static final String DOCUMENT = "sandbox/MapboxVectorTilesApi.md"; - private static final File TEMPLATE = new File(TEMPLATE_ROOT, DOCUMENT); - private static final File OUT_FILE = new File(DOCS_ROOT, DOCUMENT); + private static final File TEMPLATE = new File(TEMPLATE_PATH, DOCUMENT); + private static final File OUT_FILE = new File(USER_DOC_PATH, DOCUMENT); private static final SkipNodes SKIP_NODES = SkipNodes.of().build(); @Test diff --git a/src/ext-test/java/org/opentripplanner/ext/vehiclerentalservicedirectory/generatedoc/VehicleRentalServiceDirectoryConfigDocTest.java b/src/ext-test/java/org/opentripplanner/ext/vehiclerentalservicedirectory/generatedoc/VehicleRentalServiceDirectoryConfigDocTest.java index 4936bb4dd44..2afcd95949c 100644 --- a/src/ext-test/java/org/opentripplanner/ext/vehiclerentalservicedirectory/generatedoc/VehicleRentalServiceDirectoryConfigDocTest.java +++ b/src/ext-test/java/org/opentripplanner/ext/vehiclerentalservicedirectory/generatedoc/VehicleRentalServiceDirectoryConfigDocTest.java @@ -5,8 +5,8 @@ import static org.opentripplanner.framework.io.FileUtils.readFile; import static org.opentripplanner.framework.io.FileUtils.writeFile; import static org.opentripplanner.framework.text.MarkdownFormatter.HEADER_4; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.DOCS_ROOT; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_ROOT; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_PATH; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.USER_DOC_PATH; import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceJsonExample; import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceParametersDetails; import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceParametersTable; @@ -26,8 +26,8 @@ public class VehicleRentalServiceDirectoryConfigDocTest { private static final String DOCUMENT = "sandbox/VehicleRentalServiceDirectory.md"; - private static final File TEMPLATE = new File(TEMPLATE_ROOT, DOCUMENT); - private static final File OUT_FILE = new File(DOCS_ROOT, DOCUMENT); + private static final File TEMPLATE = new File(TEMPLATE_PATH, DOCUMENT); + private static final File OUT_FILE = new File(USER_DOC_PATH, DOCUMENT); private static final String CONFIG_PATH = "org/opentripplanner/ext/vehiclerentalservicedirectory/generatedoc/" + ROUTER_CONFIG_FILENAME; private static final String CONFIG_TAG = "vehicleRentalServiceDirectory"; diff --git a/src/test/java/org/opentripplanner/generate/doc/BuildConfigurationDocTest.java b/src/test/java/org/opentripplanner/generate/doc/BuildConfigurationDocTest.java index bc17fdc1f31..8189f18f20e 100644 --- a/src/test/java/org/opentripplanner/generate/doc/BuildConfigurationDocTest.java +++ b/src/test/java/org/opentripplanner/generate/doc/BuildConfigurationDocTest.java @@ -4,8 +4,8 @@ import static org.opentripplanner.framework.io.FileUtils.readFile; import static org.opentripplanner.framework.io.FileUtils.writeFile; import static org.opentripplanner.framework.text.MarkdownFormatter.HEADER_3; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.DOCS_ROOT; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_ROOT; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_PATH; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.USER_DOC_PATH; import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceJsonExample; import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceParametersDetails; import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceParametersTable; @@ -25,8 +25,8 @@ public class BuildConfigurationDocTest { private static final String CONFIG_JSON = OtpFileNames.BUILD_CONFIG_FILENAME; - private static final File TEMPLATE = new File(TEMPLATE_ROOT, "BuildConfiguration.md"); - private static final File OUT_FILE = new File(DOCS_ROOT, "BuildConfiguration.md"); + private static final File TEMPLATE = new File(TEMPLATE_PATH, "BuildConfiguration.md"); + private static final File OUT_FILE = new File(USER_DOC_PATH, "BuildConfiguration.md"); private static final String CONFIG_PATH = "standalone/config/" + CONFIG_JSON; private static final SkipNodes SKIP_NODES = SkipNodes diff --git a/src/test/java/org/opentripplanner/generate/doc/ConfigurationDocTest.java b/src/test/java/org/opentripplanner/generate/doc/ConfigurationDocTest.java index c310e2858a8..fed5ddb325d 100644 --- a/src/test/java/org/opentripplanner/generate/doc/ConfigurationDocTest.java +++ b/src/test/java/org/opentripplanner/generate/doc/ConfigurationDocTest.java @@ -3,8 +3,8 @@ import static org.opentripplanner.framework.io.FileUtils.assertFileEquals; import static org.opentripplanner.framework.io.FileUtils.readFile; import static org.opentripplanner.framework.io.FileUtils.writeFile; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.DOCS_ROOT; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_ROOT; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_PATH; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.USER_DOC_PATH; import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceSection; import static org.opentripplanner.generate.doc.support.ConfigTypeTable.configTypeTable; import static org.opentripplanner.generate.doc.support.OTPFeatureTable.otpFeaturesTable; @@ -16,9 +16,9 @@ @GeneratesDocumentation public class ConfigurationDocTest { - private static final File TEMPLATE = new File(TEMPLATE_ROOT, "Configuration.md"); + private static final File TEMPLATE = new File(TEMPLATE_PATH, "Configuration.md"); - private static final File OUT_FILE = new File(DOCS_ROOT, "Configuration.md"); + private static final File OUT_FILE = new File(USER_DOC_PATH, "Configuration.md"); private static final String CONFIG_TYPE_PLACEHOLDER = "CONFIGURATION-TYPES-TABLE"; private static final String OTP_FEATURE_PLACEHOLDER = "OTP-FEATURE-TABLE"; diff --git a/src/test/java/org/opentripplanner/generate/doc/EmissionsConfigurationDocTest.java b/src/test/java/org/opentripplanner/generate/doc/EmissionsConfigurationDocTest.java index 68caa043e26..5010c78d527 100644 --- a/src/test/java/org/opentripplanner/generate/doc/EmissionsConfigurationDocTest.java +++ b/src/test/java/org/opentripplanner/generate/doc/EmissionsConfigurationDocTest.java @@ -4,8 +4,8 @@ import static org.opentripplanner.framework.io.FileUtils.readFile; import static org.opentripplanner.framework.io.FileUtils.writeFile; import static org.opentripplanner.framework.text.MarkdownFormatter.HEADER_4; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.DOCS_ROOT; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_ROOT; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_PATH; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.USER_DOC_PATH; import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceSection; import static org.opentripplanner.standalone.config.framework.json.JsonSupport.jsonNodeFromResource; @@ -24,8 +24,8 @@ @GeneratesDocumentation public class EmissionsConfigurationDocTest { - private static final File TEMPLATE = new File(TEMPLATE_ROOT, "Emissions.md"); - private static final File OUT_FILE = new File(DOCS_ROOT + "/sandbox", "Emissions.md"); + private static final File TEMPLATE = new File(TEMPLATE_PATH, "Emissions.md"); + private static final File OUT_FILE = new File(USER_DOC_PATH + "/sandbox", "Emissions.md"); private static final String CONFIG_JSON = OtpFileNames.BUILD_CONFIG_FILENAME; private static final String CONFIG_PATH = "standalone/config/" + CONFIG_JSON; private static final SkipNodes SKIP_NODES = SkipNodes.of().build(); diff --git a/src/test/java/org/opentripplanner/generate/doc/FlexConfigurationDocTest.java b/src/test/java/org/opentripplanner/generate/doc/FlexConfigurationDocTest.java index fd2d7092dc5..e18090466b9 100644 --- a/src/test/java/org/opentripplanner/generate/doc/FlexConfigurationDocTest.java +++ b/src/test/java/org/opentripplanner/generate/doc/FlexConfigurationDocTest.java @@ -4,8 +4,8 @@ import static org.opentripplanner.framework.io.FileUtils.readFile; import static org.opentripplanner.framework.io.FileUtils.writeFile; import static org.opentripplanner.framework.text.MarkdownFormatter.HEADER_4; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.DOCS_ROOT; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_ROOT; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_PATH; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.USER_DOC_PATH; import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceSection; import static org.opentripplanner.standalone.config.framework.json.JsonSupport.jsonNodeFromResource; @@ -23,8 +23,8 @@ @GeneratesDocumentation public class FlexConfigurationDocTest { - private static final File TEMPLATE = new File(TEMPLATE_ROOT, "Flex.md"); - private static final File OUT_FILE = new File(DOCS_ROOT + "/sandbox", "Flex.md"); + private static final File TEMPLATE = new File(TEMPLATE_PATH, "Flex.md"); + private static final File OUT_FILE = new File(USER_DOC_PATH + "/sandbox", "Flex.md"); private static final String ROUTER_CONFIG_FILENAME = "standalone/config/router-config.json"; private static final SkipNodes SKIP_NODES = SkipNodes.of().build(); diff --git a/src/test/java/org/opentripplanner/generate/doc/GraphQLTutorialDocTest.java b/src/test/java/org/opentripplanner/generate/doc/GraphQLTutorialDocTest.java index 83e607449eb..7eb6a685cca 100644 --- a/src/test/java/org/opentripplanner/generate/doc/GraphQLTutorialDocTest.java +++ b/src/test/java/org/opentripplanner/generate/doc/GraphQLTutorialDocTest.java @@ -4,8 +4,8 @@ import static org.opentripplanner.framework.io.FileUtils.assertFileEquals; import static org.opentripplanner.framework.io.FileUtils.readFile; import static org.opentripplanner.framework.io.FileUtils.writeFile; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.DOCS_ROOT; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_ROOT; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_PATH; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.USER_DOC_PATH; import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceSection; import com.google.common.io.Resources; @@ -20,9 +20,9 @@ @GeneratesDocumentation public class GraphQLTutorialDocTest { - private static final File TEMPLATE = new File(TEMPLATE_ROOT, "GraphQL-Tutorial.md"); + private static final File TEMPLATE = new File(TEMPLATE_PATH, "GraphQL-Tutorial.md"); - private static final File OUT_FILE = new File(DOCS_ROOT + "/apis", "GraphQL-Tutorial.md"); + private static final File OUT_FILE = new File(USER_DOC_PATH + "/apis", "GraphQL-Tutorial.md"); /** * NOTE! This test updates the {@code doc/user/GraphQlTutorial.md} document based on the latest diff --git a/src/test/java/org/opentripplanner/generate/doc/RideHailingDocTest.java b/src/test/java/org/opentripplanner/generate/doc/RideHailingDocTest.java index 7ebd90260f1..2d04e002413 100644 --- a/src/test/java/org/opentripplanner/generate/doc/RideHailingDocTest.java +++ b/src/test/java/org/opentripplanner/generate/doc/RideHailingDocTest.java @@ -5,8 +5,8 @@ import static org.opentripplanner.framework.io.FileUtils.readFile; import static org.opentripplanner.framework.io.FileUtils.writeFile; import static org.opentripplanner.framework.text.MarkdownFormatter.HEADER_4; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.DOCS_ROOT; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_ROOT; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_PATH; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.USER_DOC_PATH; import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceSection; import static org.opentripplanner.standalone.config.framework.json.JsonSupport.jsonNodeFromResource; @@ -24,8 +24,8 @@ @GeneratesDocumentation public class RideHailingDocTest { - private static final File TEMPLATE = new File(TEMPLATE_ROOT, "RideHailing.md"); - private static final File OUT_FILE = new File(DOCS_ROOT + "/sandbox", "RideHailing.md"); + private static final File TEMPLATE = new File(TEMPLATE_PATH, "RideHailing.md"); + private static final File OUT_FILE = new File(USER_DOC_PATH + "/sandbox", "RideHailing.md"); private static final String ROUTER_CONFIG_PATH = "standalone/config/" + ROUTER_CONFIG_FILENAME; private static final SkipNodes SKIP_NODES = SkipNodes.of().build(); diff --git a/src/test/java/org/opentripplanner/generate/doc/RouteRequestDocTest.java b/src/test/java/org/opentripplanner/generate/doc/RouteRequestDocTest.java index 0d4f0e9cff1..b4725c5e2a1 100644 --- a/src/test/java/org/opentripplanner/generate/doc/RouteRequestDocTest.java +++ b/src/test/java/org/opentripplanner/generate/doc/RouteRequestDocTest.java @@ -5,8 +5,8 @@ import static org.opentripplanner.framework.io.FileUtils.readFile; import static org.opentripplanner.framework.io.FileUtils.writeFile; import static org.opentripplanner.framework.text.MarkdownFormatter.HEADER_3; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.DOCS_ROOT; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_ROOT; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_PATH; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.USER_DOC_PATH; import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceJsonExample; import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceParametersDetails; import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceParametersTable; @@ -25,8 +25,8 @@ @GeneratesDocumentation public class RouteRequestDocTest { - private static final File TEMPLATE = new File(TEMPLATE_ROOT, "RouteRequest.md"); - private static final File OUT_FILE = new File(DOCS_ROOT, "RouteRequest.md"); + private static final File TEMPLATE = new File(TEMPLATE_PATH, "RouteRequest.md"); + private static final File OUT_FILE = new File(USER_DOC_PATH, "RouteRequest.md"); private static final String ROUTER_CONFIG_PATH = "standalone/config/" + ROUTER_CONFIG_FILENAME; private static final SkipNodes SKIP_NODES = SkipNodes .of() diff --git a/src/test/java/org/opentripplanner/generate/doc/RouterConfigurationDocTest.java b/src/test/java/org/opentripplanner/generate/doc/RouterConfigurationDocTest.java index 2ec95c3cd05..77490c506fd 100644 --- a/src/test/java/org/opentripplanner/generate/doc/RouterConfigurationDocTest.java +++ b/src/test/java/org/opentripplanner/generate/doc/RouterConfigurationDocTest.java @@ -5,8 +5,8 @@ import static org.opentripplanner.framework.io.FileUtils.readFile; import static org.opentripplanner.framework.io.FileUtils.writeFile; import static org.opentripplanner.framework.text.MarkdownFormatter.HEADER_3; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.DOCS_ROOT; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_ROOT; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_PATH; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.USER_DOC_PATH; import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceJsonExample; import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceParametersDetails; import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceParametersTable; @@ -24,8 +24,8 @@ @GeneratesDocumentation public class RouterConfigurationDocTest { - private static final File TEMPLATE = new File(TEMPLATE_ROOT, "RouterConfiguration.md"); - private static final File OUT_FILE = new File(DOCS_ROOT, "RouterConfiguration.md"); + private static final File TEMPLATE = new File(TEMPLATE_PATH, "RouterConfiguration.md"); + private static final File OUT_FILE = new File(USER_DOC_PATH, "RouterConfiguration.md"); private static final String CONFIG_PATH = "standalone/config/" + ROUTER_CONFIG_FILENAME; private static final SkipNodes SKIP_NODES = SkipNodes diff --git a/src/test/java/org/opentripplanner/generate/doc/RoutingModeDocTest.java b/src/test/java/org/opentripplanner/generate/doc/RoutingModeDocTest.java index 0c6edc7e16b..188101e3b5d 100644 --- a/src/test/java/org/opentripplanner/generate/doc/RoutingModeDocTest.java +++ b/src/test/java/org/opentripplanner/generate/doc/RoutingModeDocTest.java @@ -3,8 +3,8 @@ import static org.opentripplanner.framework.io.FileUtils.assertFileEquals; import static org.opentripplanner.framework.io.FileUtils.readFile; import static org.opentripplanner.framework.io.FileUtils.writeFile; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.DOCS_ROOT; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_ROOT; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_PATH; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.USER_DOC_PATH; import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceSection; import java.io.File; @@ -19,8 +19,8 @@ @GeneratesDocumentation public class RoutingModeDocTest { - private static final File TEMPLATE = new File(TEMPLATE_ROOT, "RoutingModes.md"); - private static final File OUT_FILE = new File(DOCS_ROOT, "RoutingModes.md"); + private static final File TEMPLATE = new File(TEMPLATE_PATH, "RoutingModes.md"); + private static final File OUT_FILE = new File(USER_DOC_PATH, "RoutingModes.md"); @Test public void updateDocs() { diff --git a/src/test/java/org/opentripplanner/generate/doc/SiriAzureConfigDocTest.java b/src/test/java/org/opentripplanner/generate/doc/SiriAzureConfigDocTest.java index c910ee3bf7b..fcf93770f38 100644 --- a/src/test/java/org/opentripplanner/generate/doc/SiriAzureConfigDocTest.java +++ b/src/test/java/org/opentripplanner/generate/doc/SiriAzureConfigDocTest.java @@ -5,8 +5,8 @@ import static org.opentripplanner.framework.io.FileUtils.readFile; import static org.opentripplanner.framework.io.FileUtils.writeFile; import static org.opentripplanner.framework.text.MarkdownFormatter.HEADER_4; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.DOCS_ROOT; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_ROOT; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_PATH; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.USER_DOC_PATH; import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceSection; import static org.opentripplanner.standalone.config.framework.json.JsonSupport.jsonNodeFromResource; @@ -25,8 +25,8 @@ @GeneratesDocumentation public class SiriAzureConfigDocTest { - private static final File TEMPLATE = new File(TEMPLATE_ROOT, "sandbox/siri/SiriAzureUpdater.md"); - private static final File OUT_FILE = new File(DOCS_ROOT, "sandbox/siri/SiriAzureUpdater.md"); + private static final File TEMPLATE = new File(TEMPLATE_PATH, "sandbox/siri/SiriAzureUpdater.md"); + private static final File OUT_FILE = new File(USER_DOC_PATH, "sandbox/siri/SiriAzureUpdater.md"); private static final String ROUTER_CONFIG_PATH = "standalone/config/" + ROUTER_CONFIG_FILENAME; private static final Set INCLUDE_UPDATERS = Set.of( diff --git a/src/test/java/org/opentripplanner/generate/doc/SiriConfigDocTest.java b/src/test/java/org/opentripplanner/generate/doc/SiriConfigDocTest.java index 46d829cc4c3..71df3027c7d 100644 --- a/src/test/java/org/opentripplanner/generate/doc/SiriConfigDocTest.java +++ b/src/test/java/org/opentripplanner/generate/doc/SiriConfigDocTest.java @@ -5,8 +5,8 @@ import static org.opentripplanner.framework.io.FileUtils.readFile; import static org.opentripplanner.framework.io.FileUtils.writeFile; import static org.opentripplanner.framework.text.MarkdownFormatter.HEADER_4; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.DOCS_ROOT; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_ROOT; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_PATH; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.USER_DOC_PATH; import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceSection; import static org.opentripplanner.standalone.config.framework.json.JsonSupport.jsonNodeFromResource; @@ -25,8 +25,8 @@ @GeneratesDocumentation public class SiriConfigDocTest { - private static final File TEMPLATE = new File(TEMPLATE_ROOT, "sandbox/siri/SiriUpdater.md"); - private static final File OUT_FILE = new File(DOCS_ROOT, "sandbox/siri/SiriUpdater.md"); + private static final File TEMPLATE = new File(TEMPLATE_PATH, "sandbox/siri/SiriUpdater.md"); + private static final File OUT_FILE = new File(USER_DOC_PATH, "sandbox/siri/SiriUpdater.md"); private static final String ROUTER_CONFIG_PATH = "standalone/config/" + ROUTER_CONFIG_FILENAME; private static final Set INCLUDE_UPDATERS = Set.of("siri-et-updater", "siri-sx-updater"); diff --git a/src/test/java/org/opentripplanner/generate/doc/SiriGooglePubSubConfigDocTest.java b/src/test/java/org/opentripplanner/generate/doc/SiriGooglePubSubConfigDocTest.java index 342344363b3..ce414b298d0 100644 --- a/src/test/java/org/opentripplanner/generate/doc/SiriGooglePubSubConfigDocTest.java +++ b/src/test/java/org/opentripplanner/generate/doc/SiriGooglePubSubConfigDocTest.java @@ -5,8 +5,8 @@ import static org.opentripplanner.framework.io.FileUtils.readFile; import static org.opentripplanner.framework.io.FileUtils.writeFile; import static org.opentripplanner.framework.text.MarkdownFormatter.HEADER_4; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.DOCS_ROOT; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_ROOT; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_PATH; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.USER_DOC_PATH; import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceSection; import static org.opentripplanner.standalone.config.framework.json.JsonSupport.jsonNodeFromResource; @@ -26,11 +26,11 @@ public class SiriGooglePubSubConfigDocTest { private static final File TEMPLATE = new File( - TEMPLATE_ROOT, + TEMPLATE_PATH, "sandbox/siri/SiriGooglePubSubUpdater.md" ); private static final File OUT_FILE = new File( - DOCS_ROOT, + USER_DOC_PATH, "sandbox/siri/SiriGooglePubSubUpdater.md" ); diff --git a/src/test/java/org/opentripplanner/generate/doc/StopConsolidationDocTest.java b/src/test/java/org/opentripplanner/generate/doc/StopConsolidationDocTest.java index 62f76032a09..2861253aac7 100644 --- a/src/test/java/org/opentripplanner/generate/doc/StopConsolidationDocTest.java +++ b/src/test/java/org/opentripplanner/generate/doc/StopConsolidationDocTest.java @@ -3,8 +3,8 @@ import static org.opentripplanner.framework.io.FileUtils.assertFileEquals; import static org.opentripplanner.framework.io.FileUtils.readFile; import static org.opentripplanner.framework.io.FileUtils.writeFile; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.DOCS_ROOT; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_ROOT; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_PATH; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.USER_DOC_PATH; import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceSection; import static org.opentripplanner.standalone.config.framework.json.JsonSupport.jsonNodeFromResource; @@ -21,8 +21,8 @@ public class StopConsolidationDocTest { private static final String FILE_NAME = "StopConsolidation.md"; - private static final File TEMPLATE = new File(TEMPLATE_ROOT, FILE_NAME); - private static final File OUT_FILE = new File(DOCS_ROOT + "/sandbox", FILE_NAME); + private static final File TEMPLATE = new File(TEMPLATE_PATH, FILE_NAME); + private static final File OUT_FILE = new File(USER_DOC_PATH + "/sandbox", FILE_NAME); private static final String CONFIG_FILENAME = "standalone/config/build-config.json"; diff --git a/src/test/java/org/opentripplanner/generate/doc/UpdaterConfigDocTest.java b/src/test/java/org/opentripplanner/generate/doc/UpdaterConfigDocTest.java index 75d6cb6fe5a..7a3f2969c4d 100644 --- a/src/test/java/org/opentripplanner/generate/doc/UpdaterConfigDocTest.java +++ b/src/test/java/org/opentripplanner/generate/doc/UpdaterConfigDocTest.java @@ -5,8 +5,8 @@ import static org.opentripplanner.framework.io.FileUtils.readFile; import static org.opentripplanner.framework.io.FileUtils.writeFile; import static org.opentripplanner.framework.text.MarkdownFormatter.HEADER_4; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.DOCS_ROOT; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_ROOT; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_PATH; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.USER_DOC_PATH; import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceSection; import static org.opentripplanner.standalone.config.framework.json.JsonSupport.jsonNodeFromResource; @@ -25,8 +25,8 @@ @GeneratesDocumentation public class UpdaterConfigDocTest { - private static final File TEMPLATE = new File(TEMPLATE_ROOT, "UpdaterConfig.md"); - private static final File OUT_FILE = new File(DOCS_ROOT, "UpdaterConfig.md"); + private static final File TEMPLATE = new File(TEMPLATE_PATH, "UpdaterConfig.md"); + private static final File OUT_FILE = new File(USER_DOC_PATH, "UpdaterConfig.md"); private static final String ROUTER_CONFIG_PATH = "standalone/config/" + ROUTER_CONFIG_FILENAME; private static final Set SKIP_UPDATERS = Set.of( diff --git a/src/test/java/org/opentripplanner/generate/doc/VehicleParkingDocTest.java b/src/test/java/org/opentripplanner/generate/doc/VehicleParkingDocTest.java index abc9ceee806..caffafdf72b 100644 --- a/src/test/java/org/opentripplanner/generate/doc/VehicleParkingDocTest.java +++ b/src/test/java/org/opentripplanner/generate/doc/VehicleParkingDocTest.java @@ -5,8 +5,8 @@ import static org.opentripplanner.framework.io.FileUtils.readFile; import static org.opentripplanner.framework.io.FileUtils.writeFile; import static org.opentripplanner.framework.text.MarkdownFormatter.HEADER_4; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.DOCS_ROOT; -import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_ROOT; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.TEMPLATE_PATH; +import static org.opentripplanner.generate.doc.framework.DocsTestConstants.USER_DOC_PATH; import static org.opentripplanner.generate.doc.framework.TemplateUtil.replaceSection; import static org.opentripplanner.standalone.config.framework.json.JsonSupport.jsonNodeFromResource; @@ -23,8 +23,8 @@ @GeneratesDocumentation public class VehicleParkingDocTest { - private static final File TEMPLATE = new File(TEMPLATE_ROOT, "VehicleParking.md"); - private static final File OUT_FILE = new File(DOCS_ROOT + "/sandbox", "VehicleParking.md"); + private static final File TEMPLATE = new File(TEMPLATE_PATH, "VehicleParking.md"); + private static final File OUT_FILE = new File(USER_DOC_PATH + "/sandbox", "VehicleParking.md"); private static final String ROUTER_CONFIG_PATH = "standalone/config/" + ROUTER_CONFIG_FILENAME; private static final SkipNodes SKIP_NODES = SkipNodes.of().build(); diff --git a/src/test/java/org/opentripplanner/generate/doc/framework/DocsTestConstants.java b/src/test/java/org/opentripplanner/generate/doc/framework/DocsTestConstants.java index 3f9f30c30b1..a7f7afa806a 100644 --- a/src/test/java/org/opentripplanner/generate/doc/framework/DocsTestConstants.java +++ b/src/test/java/org/opentripplanner/generate/doc/framework/DocsTestConstants.java @@ -9,8 +9,9 @@ */ public interface DocsTestConstants { Logger LOG = LoggerFactory.getLogger(DocsTestConstants.class); - File TEMPLATE_ROOT = new File("doc-templates"); - File DOCS_ROOT = new File("doc/user"); + File DOC_ROOT = new File("doc"); + File TEMPLATE_PATH = new File(DOC_ROOT, "templates"); + File USER_DOC_PATH = new File(DOC_ROOT, "user"); /** * This method return {@code true} if the /docs directory is available. If not, a warning is @@ -18,7 +19,7 @@ public interface DocsTestConstants { * annotation. */ static boolean docsExistOrWarn() { - if (DOCS_ROOT.exists()) { + if (USER_DOC_PATH.exists()) { return true; } LOG.warn( From 3d37531ac1b691b880791d172b0e402619cf2506 Mon Sep 17 00:00:00 2001 From: Thomas Gran Date: Wed, 24 Jul 2024 17:17:02 +0200 Subject: [PATCH 18/21] Set user-doc directory in mkdocs.yml --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 145d3f3809e..8b3748be2b0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,7 +6,7 @@ site_name: OpenTripPlanner 2 site_url: https://docs.opentripplanner.org repo_url: https://github.com/opentripplanner/OpenTripPlanner -docs_dir: docs +docs_dir: doc/user site_dir: target/mkdocs strict: true From 759e184b48dbf17508d6c4bb1e6f9ca28961f8e5 Mon Sep 17 00:00:00 2001 From: Thomas Gran Date: Thu, 25 Jul 2024 13:48:16 +0200 Subject: [PATCH 19/21] Update doc/dev/decisionrecords/RecordsPOJOsBuilders.md --- doc/dev/decisionrecords/RecordsPOJOsBuilders.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/dev/decisionrecords/RecordsPOJOsBuilders.md b/doc/dev/decisionrecords/RecordsPOJOsBuilders.md index 34019d503e6..1a836374181 100644 --- a/doc/dev/decisionrecords/RecordsPOJOsBuilders.md +++ b/doc/dev/decisionrecords/RecordsPOJOsBuilders.md @@ -16,7 +16,7 @@ Builder initStop(Stop stop) { You may use records, but avoid using records if you can not encapsulate it properly. Be especially aware of arrays fields (can not be protected) and collections (remember to make a defensive copy). If you need to override `equals` and `hashCode`, then it is probably not worth it. -Be aware that `equals` compare references, not the value of a field. Consider overriding `toString`. +The default `equals()` and `hashCode()` implementation is shallow, so all nested fields need to be records or value-objects. Consider overriding `toString`. ### Builders From 90fd6a4ebb312a4d0a257f0b9ee6d9b08c019795 Mon Sep 17 00:00:00 2001 From: Thomas Gran Date: Fri, 26 Jul 2024 12:00:39 +0200 Subject: [PATCH 20/21] Apply suggestions from code review Co-authored-by: Andrew Byrd --- doc/dev/decisionrecords/UseDecisionRecords.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/dev/decisionrecords/UseDecisionRecords.md b/doc/dev/decisionrecords/UseDecisionRecords.md index d30c255e556..800c8340904 100644 --- a/doc/dev/decisionrecords/UseDecisionRecords.md +++ b/doc/dev/decisionrecords/UseDecisionRecords.md @@ -1,8 +1,8 @@ # Decision Records [TODO - Not precise] An OTP Decision Record is a justified software design choice that addresses a -functional or non-functional requirement that is significant. [Architectural Decision Records](https://adr.github.io/) -is a similar concept, but we have widened the scope to include any relevant decision about the +significant functional or non-functional requirement. [Architectural Decision Records](https://adr.github.io/) +is a similar concept, but we have widened the scope to include any relevant decision about OTP development. ## Process From cd9e9737810b11f073a22eccdc50f7853b60eb26 Mon Sep 17 00:00:00 2001 From: Thomas Gran Date: Wed, 21 Aug 2024 12:18:38 +0200 Subject: [PATCH 21/21] Update doc/dev/decisionrecords/RecordsPOJOsBuilders.md Co-authored-by: Andrew Byrd --- doc/dev/decisionrecords/RecordsPOJOsBuilders.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/doc/dev/decisionrecords/RecordsPOJOsBuilders.md b/doc/dev/decisionrecords/RecordsPOJOsBuilders.md index 1a836374181..e0752fc70b0 100644 --- a/doc/dev/decisionrecords/RecordsPOJOsBuilders.md +++ b/doc/dev/decisionrecords/RecordsPOJOsBuilders.md @@ -13,10 +13,8 @@ Builder initStop(Stop stop) { ### Records -You may use records, but avoid using records if you can not encapsulate it properly. Be especially -aware of arrays fields (can not be protected) and collections (remember to make a defensive copy). -If you need to override `equals` and `hashCode`, then it is probably not worth it. -The default `equals()` and `hashCode()` implementation is shallow, so all nested fields need to be records or value-objects. Consider overriding `toString`. +You may use records, but avoid using records if you cannot encapsulate them properly. Generally, records are considered appropriate and useful for throw-away compound types private to an implementation, such as hash table keys or compound values in a temporary list or set. On the other hand, records are generally not appropriate in the domain model where we insist on full encapsulation, which records cannot readily provide. Be especially +aware of array fields (which can not be protected) and collections (remember to make a defensive copy). Consider overriding `toString`. But if you need to override `equals` and `hashCode`, then it is probably not worth using a record. The implicit `equals()` and `hashCode()` implementations for records behave as if they call `equals` and `hashCode` on each field of the record, so their behavior will depend heavily on the types of these fields. ### Builders