The Importance of API
Having a consistent and functional API is critical in software development. There is a famous saying that goes like this: "API is forever". This is true. Once a class, interface or method is public or protected, it cannot be deleted and is expected to function until the end of time, even when deprecated.
Due to the number of different packages, sometimes a method needs to be public or protected so that it can be called as part of the implementation of OpenJFX. Such methods have the "imp_" prefix. These methods are not API and can be deleted or changed at any time (the JavaDoc clearly states this).
Steps for API Review
Because API is so important, there are a few restrictions over and above the normal code review process:
- Ensure that there is a JIRA that covers the work
- Add the label 'api' to the JIRA
- Notify open-jfx that there is an API review in progress
- Ensure there is a pre-commit review of the code
- In addition to the normal reviewers, an +1 is required from the Team Lead or an Architect
Behavioural Changes
Changes in behaviour can break the users of the toolkit. Major changes in behaviour such as threading should be treated like API and require the same steps as an API review. It is critical that the Team Lead and Architects are aware of how the toolkit behaves and understand how it can be used.
While API is easy to define, behavioural changes can be fuzzy. When in doubt, ask.