The actual API development and marking some part of the API as internal or add new API is an ongoing task, that will need to be done everytime. We won't just define an API and then are done with it. The API will change as new features want to be implemented.

So we should only make sure we document

• what the criteria is for a public API
  • clear-cut between public APIs and internal
  • which packages to use, e.g. internal for internal "API"
  • when to use package impl
• how to deprecate and remove old APIs
  • how long to support a given API
  • with respect to semantic version
• when to define a new API as experimental
• when to promote a experimental API as stable
• annotations to use, see also https://github.com/pmd/pmd/blob/master/docs/pages/next_major_development.md#new-api-support-guidelines
• guidelines for AST classes (package private ctor, final, etc.)

The documentation should be part of the "Architecture Decision Records" -> https://pmd.github.io/latest/pmd_projectdocs_decisions.html

Old info

(Low priority for now, but should not be lost)

Original discussion, with the main ideas repeated here:

I think at some point we need to clear-cut which APIs are public and which are not (ie: by using internal packages as Gradle does). Up until then, developers may assume anything is at their disposition.

RxJava also uses some specific annotations (@Experimental, @Beta). Maybe we could even have a @ReservedSubclassing one, to express that a class or interface is not meant to be subclassed by external clients, and that its inheritance-specific members are private API, while public members are still public API. Which would be useful for all AST related interfaces for example.

maybe, concrete AST node classes should have a package-private constructor, and be final. They're not meant to be instantiated by hand, but that could break some tests and rules

Clearly defining the API PMD provides, makes sense and will help, if we at some time in the future want to modularize PMD using java9. That would prevent API leaking then at compile time already...

Edit: I think none of pmd-ui should be considered public API, for the unforeseable future

I think we could also talk about an approximate schedule, eg

• Do we announce which APIs will be made private and deprecate them in a minor release (eg 6.3.0) and make the actual changes in the next major release (7.0.0)?
• Do we announce which APIs will be made private and deprecate them in a major release (eg 7.0.0) and make the actual changes in the next major release (8.0.0)?
• A bit of both, depending on the level of "breaking" we're talking about? E.g. deprecating the subclassing of node classes and such in a minor release, and making related breaking changes in 7.0.0, while keeping the moving of private API into an internal package for 8.0.0