Hi all,
I propose that TinkerPop define a common “Experimental API” designation for
APIs/features that are not covered by the usual backward-compatibility
guarantee and may change incompatibly or be removed in a subsequent minor
release. This designation should be distinct from deprecation, since an
experimental API is still under development rather than scheduled for
removal. Software is moving increasingly fast these days and our current
policy would force us to continually make major versions for small changes
to newer APIs. This will allow us to move faster without having to maintain
lots of release branches.
Each GLV should express this status using its language’s customary
mechanism (if available), but it would rely heavily on documentation.
For Java, TinkerPop could provide its own documented `@Experimental`
annotation with a `since` value. The Javadoc should also contain an
`@apiNote` explaining the compatibility implications. Gremlin-JavaScript
could use the standard TSDoc `@experimental` tag. Gremlin.Net could use
`System.Diagnostics.CodeAnalysis.ExperimentalAttribute`, for example
`[Experimental("TPNET0001")]`. Gremlin-Python has no standard experimental
decorator or API metadata. Experimental classes and functions should
therefore begin their docstrings with a consistent “Experimental API”
warning. Gremlin-Go similarly has no experimental annotation. Exported
experimental symbols should contain an “Experimental:” paragraph in their
Go documentation comment.
The versioning documentation should explicitly define this as an exception
to the current rule that minor releases are backward compatible. Without
that policy change, source annotations and documentation warnings would
contradict TinkerPop’s existing compatibility promise.
Thanks,
Ken
