Declare our Public API for use with semantic versioning #619

Open
jeenbroekstra opened this Issue Oct 14, 2016 · 1 comment

Comments

2 participants
@jeenbroekstra
Contributor

jeenbroekstra commented Oct 14, 2016

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:

  1. what's the best way to document/specify what we consider the RDF4J public API?
  2. which parts of the code base should be part of it?
@ansell

This comment has been minimized.

Show comment
Hide comment
@ansell

ansell Oct 14, 2016

Contributor

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:

https://github.com/siom79/japicmp

Another is the animal sniffer maven plugin:

http://www.mojohaus.org/animal-sniffer/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.

Contributor

ansell commented Oct 14, 2016

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:

https://github.com/siom79/japicmp

Another is the animal sniffer maven plugin:

http://www.mojohaus.org/animal-sniffer/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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment