Sandbox for experimental features - OTP2

[t2gran]

THIS NEEDS APPROVAL FROM THE PLC

Related issues

• Design modular architecture for plugins, non-core functionality #2625 Design modular architecture for plugins, non-core functionality

Stakeholders

• Submitter - The developers/organisation submitting the new feature
• Approvers - The OTP project list of developer and PLC committee.

Definitions

• Main code - Existing code and resources including tests. (src/main, src/test)
• Extension code - New feature implementation, except code in the main code. (src/ext/<Extension name>)

Goals

• Reduce work for PR approval
• Allow experimental code to evolve
• Encourage refactoring and creation of extension points in the main code.
• Increase visibility of development of new features.
• Feature toggle
  • Default off
  • In the (build|route).config there should be a list of enabled extensions. To enable an extension add the name of the extencion to the list.

Contract

• New feature is isolated from the rest of the code by putting it in the Maven directory src/ext/java and with Java package prefix org.opentripplanner.ext.<ext_name>.
• To integrate the new feature into OTP we encourage the creation of extension points in the main code.
• There should be a README.md file in the <Extension name> package including:
  • Contact info
  • Change log
  • Documentation of the feature (optional)
• Feature is disabled by default. A feature is toggled on using the config files.
• Only code modifying the main code(src/main, not src/ext) is reviewed, but the current coding standard apply to the extension code as well - but is not necessarily reviewed.
• Anyone can request the feature to be merged into the main code. An approval from the PLC and a new review is then required. The reviewers may request any changes including API changes. No BACKWARD compatibility is guaranteed.
• The feature submitters is responsible for maintaining and testing the extension code, but do not need to provide any guarantees or support.
• When someone at a later point in time want to change the main code the only thing they are responsible for (with regard to the extension code) is that it compiles and that the unit tests run. If a test is not easy to fix, it can be tagged with @ignore.
• Changes to the main OTP API that cannot be toggled in must be clearly marked/tagged as part of an experimental feature and documented.
• If a feature is old and not maintained it can be removed 1 month after notifying the submitter (using contact info in README file).
• Introducing new dependencies needs approval. They are NOT approved if they are likely to be a maintenance challenge (many transitive dependencies or potential conflicts with other versions/libraries).

Context

• This should not be used for bug fixes and smaller changes.
• Consider forking if the feature is valuable to one deployment only.