Relabel experimental features as preview

Add definition in README
neo4j · Mar 31, 2023 · ec2268f · ec2268f
1 parent c9bec0c
commit ec2268f
Show file tree

Hide file tree

Showing 4 changed files with 72 additions and 34 deletions.
diff --git a/README.md b/README.md
@@ -43,6 +43,26 @@ go get github.com/neo4j/neo4j-go-driver
 Drivers manual that describes general driver concepts in depth [here](https://neo4j.com/docs/go-manual/current/).
 Go package API documentation [here](https://pkg.go.dev/github.com/neo4j/neo4j-go-driver/v5).
 
+## Preview Features
+
+The preview feature is a new feature that is a candidate for a future <abbr title="Generally Available">GA</abbr>
+status.
+
+It enables users to try the feature out and maintainers to refine and update it.
+
+The preview features are not considered to be experimental, temporary or unstable.
+
+However, they may change more rapidly, without following the usual deprecation cycle.
+
+Most preview features are expected to be granted the GA status unless some unexpected conditions arise.
+
+Due to the increased flexibility of the preview status, user feedback is encouraged so that it can be considered before
+the GA status.
+
+Every preview feature gets a
+dedicated [GitHub Discussion](https://github.com/neo4j/neo4j-go-driver/discussions/categories/preview-feature-announcement)
+where users can share their initial impressions and thoughts.
+
 ## Migrating from previous versions
 
 See [migration guide](MIGRATION_GUIDE.md) for information on how to migrate 
@@ -145,20 +165,22 @@ func (i *Item) String() string {
 Please look at the [supported version's documentation](https://neo4j.com/developer/kb/neo4j-supported-versions/) for the
 most accurate information about Neo4j releases.
 
-| Server \\ Driver    | 1.7 | 4.0 | 4.2   | 4.3   | **4.4** | 5.0   | 5.1   | 5.2   | 5.3   | 5.4   | 5.5   |
-|---------------------|-----|-----|-------|-------|---------|-------|-------|-------|-------|-------|-------|
-| Neo4j 3.5 (EOL)     | Yes | Yes | (Yes) | (Yes) | (Yes)   | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) |
-| Neo4j 4.0 (EOL)     | Yes | Yes | Yes   | Yes   | Yes     | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) |
-| Neo4j 4.1 (EOL)     | ?   | Yes | Yes   | Yes   | Yes     | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) |
-| Neo4j 4.2 (EOL)     | ?   | ?   | Yes   | Yes   | Yes     | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) |
-| Neo4j 4.3 (EOL)     | ?   | ?   | Yes   | Yes   | Yes     | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) |
-| **Neo4j 4.4 (LTS)** | ?   | ?   | ?     | Yes   | Yes     | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   |
-| Neo4j 5.0 (HO)      | ?   | ?   | ?     | ?     | Yes     | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   |
-| Neo4j 5.1 (HO)      | ?   | ?   | ?     | ?     | (Yes)   | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   |
-| Neo4j 5.2 (HO)      | ?   | ?   | ?     | ?     | (Yes)   | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   |
-| Neo4j 5.3 (HO)      | ?   | ?   | ?     | ?     | (Yes)   | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   |
-| Neo4j 5.4           | ?   | ?   | ?     | ?     | (Yes)   | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   |
-| Neo4j 5.5           | ?   | ?   | ?     | ?     | (Yes)   | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   |
+| Server \\ Driver    | 1.7 | 4.0 | 4.2   | 4.3   | **4.4** | 5.0   | 5.1   | 5.2   | 5.3   | 5.4   | 5.5   | 5.6   | 5.7   |
+|---------------------|-----|-----|-------|-------|---------|-------|-------|-------|-------|-------|-------|-------|-------|
+| Neo4j 3.5 (EOL)     | Yes | Yes | (Yes) | (Yes) | (Yes)   | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) |
+| Neo4j 4.0 (EOL)     | Yes | Yes | Yes   | Yes   | Yes     | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) |
+| Neo4j 4.1 (EOL)     | ?   | Yes | Yes   | Yes   | Yes     | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | 
+| Neo4j 4.2 (EOL)     | ?   | ?   | Yes   | Yes   | Yes     | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | 
+| Neo4j 4.3 (EOL)     | ?   | ?   | Yes   | Yes   | Yes     | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | 
+| **Neo4j 4.4 (LTS)** | ?   | ?   | ?     | Yes   | Yes     | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   | (Yes) | 
+| Neo4j 5.0 (HO)      | ?   | ?   | ?     | ?     | Yes     | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   | (Yes) | 
+| Neo4j 5.1 (HO)      | ?   | ?   | ?     | ?     | (Yes)   | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   | (Yes) | 
+| Neo4j 5.2 (HO)      | ?   | ?   | ?     | ?     | (Yes)   | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   | (Yes) | 
+| Neo4j 5.3 (HO)      | ?   | ?   | ?     | ?     | (Yes)   | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   | (Yes) | 
+| Neo4j 5.4 (HO)      | ?   | ?   | ?     | ?     | (Yes)   | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   | (Yes) | 
+| Neo4j 5.5 (HO)      | ?   | ?   | ?     | ?     | (Yes)   | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   | (Yes) | 
+| Neo4j 5.6           | ?   | ?   | ?     | ?     | (Yes)   | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   | (Yes) |
+| Neo4j 5.7           | ?   | ?   | ?     | ?     | (Yes)   | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   | Yes   |
 
 - `(EOL)`: End Of Life, a server version is marked as such when it is not supported anymore
 - `(HO)`: Hotfixes only, a server version is marked as such when it is only updated for security patches

diff --git a/neo4j/bookmarks.go b/neo4j/bookmarks.go
@@ -32,7 +32,7 @@ import (
 type Bookmarks = []string
 
 // BookmarkManager centralizes bookmark manager supply and notification
-// This API is experimental and may be changed or removed without prior notice
+// This is currently a preview feature (see README on what it means in terms of support and compatibility guarantees)
 type BookmarkManager interface {
 	// UpdateBookmarks updates the bookmark tracked by this bookmark manager
 	// previousBookmarks are the initial bookmarks of the bookmark holder (like a Session)
@@ -44,8 +44,8 @@ type BookmarkManager interface {
 	GetBookmarks(ctx context.Context) (Bookmarks, error)
 }
 
-// BookmarkManagerConfig is an experimental API and may be changed or removed
-// without prior notice
+// BookmarkManagerConfig is part of the BookmarkManager preview feature (see README on what it means in terms of support
+// and compatibility guarantees)
 type BookmarkManagerConfig struct {
 	// Initial bookmarks per database
 	InitialBookmarks Bookmarks

diff --git a/neo4j/driver_with_context.go b/neo4j/driver_with_context.go
@@ -52,7 +52,8 @@ const (
 type DriverWithContext interface {
 	// DefaultExecuteQueryBookmarkManager returns the bookmark manager instance used by ExecuteQuery by default.
 	//
-	// This API is currently experimental and may change or be removed at any time.
+	// DefaultExecuteQueryBookmarkManager is part of the BookmarkManager preview feature (see README on what it means in
+	// terms of support and compatibility guarantees)
 	//
 	// This is useful when ExecuteQuery is called without custom bookmark managers and the lower-level
 	// neo4j.SessionWithContext APIs are called as well.
@@ -87,7 +88,8 @@ type DriverWithContext interface {
 
 // ResultTransformer is a record accumulator that produces an instance of T when the processing of records is over.
 //
-// This API is currently experimental and may change or be removed at any time.
+// ResultTransformer is part of the ExecuteQuery preview feature (see README on what it means in terms of support
+// and compatibility guarantees)
 type ResultTransformer[T any] interface {
 	// Accept is called whenever a new record is fetched from the server
 	// Implementers are free to accumulate or discard the specified record
@@ -350,7 +352,7 @@ func (d *driverWithContext) Close(ctx context.Context) error {
 // ExecuteQuery runs the specified query with its parameters and returns the query result, transformed by the specified
 // ResultTransformer function.
 //
-// This API is currently experimental and may change or be removed at any time.
+// This is currently a preview feature (see README on what it means in terms of support and compatibility guarantees)
 //
 //	result, err := ExecuteQuery[*EagerResult](ctx, driver, query, params, EagerResultTransformer)
 //
@@ -545,12 +547,14 @@ func (e *eagerResultTransformer) Complete(keys []string, summary ResultSummary)
 
 // ExecuteQueryConfigurationOption is a callback that configures the execution of DriverWithContext.ExecuteQuery
 //
-// This API is currently experimental and may change or be removed at any time.
+// ExecuteQueryConfigurationOption is part of the ExecuteQuery preview feature (see README on what it means in terms of
+// support and compatibility guarantees)
 type ExecuteQueryConfigurationOption func(*ExecuteQueryConfiguration)
 
 // ExecuteQueryWithReadersRouting configures DriverWithContext.ExecuteQuery to route to reader members of the cluster
 //
-// This API is currently experimental and may change or be removed at any time.
+// ExecuteQueryWithReadersRouting is part of the ExecuteQuery preview feature (see README on what it means in terms of
+// support and compatibility guarantees)
 func ExecuteQueryWithReadersRouting() ExecuteQueryConfigurationOption {
 	return func(configuration *ExecuteQueryConfiguration) {
 		configuration.Routing = Readers
@@ -559,7 +563,8 @@ func ExecuteQueryWithReadersRouting() ExecuteQueryConfigurationOption {
 
 // ExecuteQueryWithWritersRouting configures DriverWithContext.ExecuteQuery to route to writer members of the cluster
 //
-// This API is currently experimental and may change or be removed at any time.
+// ExecuteQueryWithWritersRouting is part of the ExecuteQuery preview feature (see README on what it means in terms of
+// support and compatibility guarantees)
 func ExecuteQueryWithWritersRouting() ExecuteQueryConfigurationOption {
 	return func(configuration *ExecuteQueryConfiguration) {
 		configuration.Routing = Writers
@@ -568,7 +573,8 @@ func ExecuteQueryWithWritersRouting() ExecuteQueryConfigurationOption {
 
 // ExecuteQueryWithImpersonatedUser configures DriverWithContext.ExecuteQuery to impersonate the specified user
 //
-// This API is currently experimental and may change or be removed at any time.
+// ExecuteQueryWithImpersonatedUser is part of the ExecuteQuery preview feature (see README on what it means in terms of
+// support and compatibility guarantees)
 func ExecuteQueryWithImpersonatedUser(user string) ExecuteQueryConfigurationOption {
 	return func(configuration *ExecuteQueryConfiguration) {
 		configuration.ImpersonatedUser = user
@@ -577,7 +583,8 @@ func ExecuteQueryWithImpersonatedUser(user string) ExecuteQueryConfigurationOpti
 
 // ExecuteQueryWithDatabase configures DriverWithContext.ExecuteQuery to target the specified database
 //
-// This API is currently experimental and may change or be removed at any time.
+// ExecuteQueryWithDatabase is part of the ExecuteQuery preview feature (see README on what it means in terms of
+// support and compatibility guarantees)
 func ExecuteQueryWithDatabase(db string) ExecuteQueryConfigurationOption {
 	return func(configuration *ExecuteQueryConfiguration) {
 		configuration.Database = db
@@ -586,7 +593,8 @@ func ExecuteQueryWithDatabase(db string) ExecuteQueryConfigurationOption {
 
 // ExecuteQueryWithBookmarkManager configures DriverWithContext.ExecuteQuery to rely on the specified BookmarkManager
 //
-// This API is currently experimental and may change or be removed at any time.
+// ExecuteQueryWithBookmarkManager is part of the ExecuteQuery preview feature (see README on what it means in terms of
+// support and compatibility guarantees)
 func ExecuteQueryWithBookmarkManager(bookmarkManager BookmarkManager) ExecuteQueryConfigurationOption {
 	return func(configuration *ExecuteQueryConfiguration) {
 		configuration.BookmarkManager = bookmarkManager
@@ -595,7 +603,8 @@ func ExecuteQueryWithBookmarkManager(bookmarkManager BookmarkManager) ExecuteQue
 
 // ExecuteQueryWithoutBookmarkManager configures DriverWithContext.ExecuteQuery to not rely on any BookmarkManager
 //
-// This API is currently experimental and may change or be removed at any time.
+// ExecuteQueryWithoutBookmarkManager is part of the ExecuteQuery preview feature (see README on what it means in terms of
+// support and compatibility guarantees)
 func ExecuteQueryWithoutBookmarkManager() ExecuteQueryConfigurationOption {
 	return func(configuration *ExecuteQueryConfiguration) {
 		configuration.BookmarkManager = nil
@@ -604,7 +613,8 @@ func ExecuteQueryWithoutBookmarkManager() ExecuteQueryConfigurationOption {
 
 // ExecuteQueryWithBoltLogger configures DriverWithContext.ExecuteQuery to log Bolt messages with the provided BoltLogger
 //
-// This API is currently experimental and may change or be removed at any time.
+// ExecuteQueryWithBoltLogger is part of the ExecuteQuery preview feature (see README on what it means in terms of
+// support and compatibility guarantees)
 func ExecuteQueryWithBoltLogger(boltLogger log.BoltLogger) ExecuteQueryConfigurationOption {
 	return func(configuration *ExecuteQueryConfiguration) {
 		configuration.BoltLogger = boltLogger
@@ -613,7 +623,8 @@ func ExecuteQueryWithBoltLogger(boltLogger log.BoltLogger) ExecuteQueryConfigura
 
 // ExecuteQueryConfiguration holds all the possible configuration settings for DriverWithContext.ExecuteQuery
 //
-// This API is currently experimental and may change or be removed at any time.
+// ExecuteQueryConfiguration is part of the ExecuteQuery preview feature (see README on what it means in terms of
+// support and compatibility guarantees)
 type ExecuteQueryConfiguration struct {
 	Routing          RoutingControl
 	ImpersonatedUser string
@@ -624,17 +635,20 @@ type ExecuteQueryConfiguration struct {
 
 // RoutingControl specifies how the query executed by DriverWithContext.ExecuteQuery is to be routed
 //
-// This API is currently experimental and may change or be removed at any time.
+// RoutingControl is part of the ExecuteQuery preview feature (see README on what it means in terms of support and
+// compatibility guarantees)
 type RoutingControl int
 
 const (
 	// Writers routes the query to execute to a writer member of the cluster
 	//
-	// This API is currently experimental and may change or be removed at any time.
+	// Writers is part of the ExecuteQuery preview feature (see README on what it means in terms of
+	// support and compatibility guarantees)
 	Writers RoutingControl = iota
 	// Readers routes the query to execute to a writer member of the cluster
 	//
-	// This API is currently experimental and may change or be removed at any time.
+	// Readers is part of the ExecuteQuery preview feature (see README on what it means in terms of
+	// support and compatibility guarantees)
 	Readers
 )
 
@@ -662,7 +676,8 @@ func (c *ExecuteQueryConfiguration) selectTxFunctionApi(session SessionWithConte
 
 // EagerResult holds the result and result metadata of the query executed via DriverWithContext.ExecuteQuery
 //
-// This API is currently experimental and may change or be removed at any time.
+// EagerResult is part of the ExecuteQuery preview feature (see README on what it means in terms of
+// support and compatibility guarantees)
 type EagerResult struct {
 	Keys    []string
 	Records []*Record

diff --git a/neo4j/session_with_context.go b/neo4j/session_with_context.go
@@ -150,7 +150,8 @@ type SessionConfig struct {
 	ImpersonatedUser string
 	// BookmarkManager defines a central point to externally supply bookmarks
 	// and be notified of bookmark updates per database
-	// This is experimental and may be changed or removed without prior notice
+	// This is part of the BookmarkManager preview feature (see README on what it means in terms of
+	// support and compatibility guarantees)
 	// Since 5.0
 	// default: nil (no-op)
 	BookmarkManager BookmarkManager