Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Declare our Public API for use with semantic versioning #619
We are aiming to apply semantic versioning, and to a large degree already follow its principles. However, a requirement of SemVer is that we have explicitly specified what our public API is.
Clearly, not every public class/method in the RDF4J code base is considered part of the public API - some of these are "internal", and are declared public for technical reasons rather than a statement that every user can/should use them and rely on their behavior to remain unchanged for minor/patch versions.
A good starting point is that all "...-api" modules and all public interfaces are considered part of the public API. But we'll need to go further than that - I assume at least a large part of the abstract implementations and a lot of utility code and some public classes should be considered part of the public API as well.
Two main questions:
As you say the -api modules are a given for consideration, although the ".impl" or ".util" packages within them could be off limits if they are only intended to be used by other RDF4J modules.
The repository-sail module is a substantially reused link between the Repository and Sail APIs so it should be on the Public API.
There is a clear service driven access service to the specific parser modules within rio along with extensive configuration options that should make it possible to leave the individual parser implementations and entire modules off the public API. However, given that they are reused and overridden by third-parties, we should still take them into account and try hard to deprecate signatures in them rather than remove signatures.
The service driven creation and configuration for the sail and repository APIs are not as broadly used and almost all calls into them are done through constructors for the various Sail/Repository implementations. So it may require some modification to the service driven approach for those to make them a little simpler and more broadly used before pushing those constructors to the internal API.
In terms of programmatic verification of the API before releases, one recent tool that we could look at is:
Another is the animal sniffer maven plugin:
It may be useful to put removals to a broader public API off until a major version bump such as 3.0 and work with deprecations solely before then.