Merge remote-tracking branch 'upstream/dev-2.x' into upstream-merge-2…

…024-09-04

.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.
 

.github/workflows/cibuild.yml

@@ -151,7 +151,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

.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

.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/

ARCHITECTURE.md

@@ -1,32 +1,36 @@
 # OTP Architecture
 
-OTP is developed over more than 10 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
 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.
 
-Be sure to also read the [developer documentation](docs/Developers-Guide.md).
+We document [Decision Records](DEVELOPMENT_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.
+
+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/dev/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 
    usually stateless; Hence the `Use Case Service` does normally not have a model. The implementing
    class has the same name as the interface with prefix `Default`.
  - `Domain Model` A model which 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. 
 
@@ -41,10 +45,6 @@ but this is a start and we would like to expand this list in the future.
 The Configuration module is responsible for loading and parsing OTP configuration files and map them
 into Plan Old Java Objects (POJOs). These POJOs are injected into the other components.
 
-### [REST API](src/main/java/org/opentripplanner/api/package.md)
-
-Short introduction to the REST API.
-
 ### [GTFS import module](src/main/java/org/opentripplanner/gtfs/package.md)
 
 Used to import GTFS transit data files.

DEVELOPMENT_DECISION_RECORDS.md

@@ -0,0 +1,106 @@
+# Development Decision 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](doc/user/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 `<module-name>/configure/<Module-name>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)
+
+