Merge pull request #1181 from ydb-platform/versioning

Versioning policy

Author: asmyasnikov

CHANGELOG.md

@@ -1,3 +1,5 @@
+* Added versioning policy
+
 ## v3.62.0
 * Restored `WithSessionPoolKeepAliveMinSize` and `WithSessionPoolKeepAliveTimeout` for backward compatibility.
 * Fixed leak timers

README.md

@@ -22,6 +22,10 @@ Supports `table`, `query`, `discovery`, `coordination`, `ratelimiter`, `scheme`,
 `ydb-go-sdk` supports all Go versions supported by the official [Go Release Policy](https://go.dev/doc/devel/release#policy). 
 That is, the two most recent releases of Go.
 
+## Versioning Policy
+
+`ydb-go-sdk` comply to guidelines from [SemVer2.0.0](https://semver.org/) with an several [exceptions](VERSIONING.md).
+
 ## Installation
 
 ```sh

VERSIONING.md

@@ -0,0 +1,24 @@
+# YDB-Go-SDK Versioning Policy
+
+By adhering to these guidelines and exceptions, we aim to provide a stable and reliable development experience for our users (aka [LTS](https://en.wikipedia.org/wiki/Long-term_support)) while still allowing for innovation and improvement.
+
+We endeavor to adhere to versioning guidelines as defined by [SemVer2.0.0](https://semver.org/).
+
+We making the following exceptions to those guidelines:
+## Experimental
+   - We use the `// Experimental` comment for new features in the `ydb-go-sdk`. 
+   - Early adopters of newest feature can report bugs and imperfections in functionality. 
+   - For fix this issues we can make broken changes in experimental API. 
+   - We reserve the right to remove or modify these experimental features at any time without increase of major part of version.
+   - We want to make experimental API as stable in the future
+## Deprecated
+   - We use the `// Deprecated` comment for deprecated features in the `ydb-go-sdk`.
+   - Usage of some entity marked with `// Deprecated` can be detected with linters such as [check-deprecated](https://github.com/black-06/check-deprecated), [staticcheck](https://github.com/dominikh/go-tools/tree/master/cmd/staticcheck) or [go-critic](https://github.com/go-critic/go-critic).
+   - This helps to our users to soft decline to use the deprecated feature without any impact on their code.
+   - Deprecated features will not be removed or changed for a minimum period of **six months** since the mark added.
+   - We reserve the right to remove or modify these deprecated features without increase of major part of version.
+## Internals
+   - Some public API of `ydb-go-sdk` relate to the internals.
+   - We use the `// Internals` comment for public internals in the `ydb-go-sdk`.
+   - `ydb-go-sdk` internals can be changed at any time without increase of major part of version.
+   - Internals will never marked as stable    

balancers/balancers.go

@@ -9,7 +9,9 @@ import (
 	"github.com/ydb-platform/ydb-go-sdk/v3/internal/xstring"
 )
 
-// Deprecated: RoundRobin is RandomChoice now
+// Deprecated: RoundRobin is an alias to RandomChoice now
+// Will be removed after Oct 2024.
+// Read about versioning policy: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#deprecated
 func RoundRobin() *balancerConfig.Config {
 	return &balancerConfig.Config{}
 }
@@ -115,6 +117,8 @@ type Endpoint interface {
 
 	// Deprecated: LocalDC check "local" by compare endpoint location with discovery "selflocation" field.
 	// It work good only if connection url always point to local dc.
+	// Will be removed after Oct 2024.
+	// Read about versioning policy: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#deprecated
 	LocalDC() bool
 }
 

config/config.go

@@ -107,7 +107,9 @@ type Option func(c *Config)
 
 // WithInternalDNSResolver
 //
-// Deprecated: always used internal dns-resolver
+// Deprecated: always used internal dns-resolver.
+// Will be removed after Oct 2024.
+// Read about versioning policy: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#deprecated
 func WithInternalDNSResolver() Option {
 	return func(c *Config) {}
 }
@@ -170,7 +172,9 @@ func WithApplicationName(applicationName string) Option {
 
 // WithUserAgent add provided user agent to all api requests
 //
-// Deprecated: use WithApplicationName instead
+// Deprecated: use WithApplicationName instead.
+// Will be removed after Oct 2024.
+// Read about versioning policy: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#deprecated
 func WithUserAgent(userAgent string) Option {
 	return func(c *Config) {
 		c.metaOptions = append(c.metaOptions, meta.WithApplicationNameOption(userAgent))

connection.go

@@ -16,10 +16,10 @@ import (
 // Connection interface provide access to YDB service clients
 // Interface and list of clients may be changed in the future
 //
-// Deprecated: use directly *Driver type from ydb.Open instead
-//
-//nolint:interfacebloat
-type Connection interface {
+// Deprecated: use Driver instance instead.
+// Will be removed at next major release.
+// Read about versioning policy: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#deprecated
+type Connection interface { //nolint:interfacebloat
 	// Endpoint returns initial endpoint
 	Endpoint() string
 
@@ -37,9 +37,7 @@ type Connection interface {
 
 	// Query returns query client
 	//
-	// # Experimental
-	//
-	// Notice: This API is EXPERIMENTAL and may be changed or removed in a later release.
+	// Experimental: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#experimental
 	Query() query.Client
 
 	// Scheme returns scheme client

coordination/coordination.go

@@ -26,9 +26,7 @@ type Client interface {
 	// - close the Client which the session was created with,
 	// - call any method of the Session until the ErrSessionClosed is returned.
 	//
-	// # Experimental
-	//
-	// Notice: This API is EXPERIMENTAL and may be changed or removed in a later release.
+	// Experimental: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#experimental
 	Session(ctx context.Context, path string, opts ...options.SessionOption) (Session, error)
 }
 

driver.go

@@ -191,9 +191,7 @@ func (d *Driver) Table() table.Client {
 
 // Query returns query client
 //
-// # Experimental
-//
-// Notice: This API is EXPERIMENTAL and may be changed or removed in a later release.
+// Experimental: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#experimental
 func (d *Driver) Query() query.Client {
 	return d.query.Get()
 }
@@ -275,10 +273,12 @@ func MustOpen(ctx context.Context, dsn string, opts ...Option) *Driver {
 
 // New connects to database and return driver runtime holder
 //
-// Deprecated: use Open with required param connectionString instead
-//
-//nolint:nonamedreturns
-func New(ctx context.Context, opts ...Option) (_ *Driver, err error) {
+// Deprecated: use ydb.Open instead.
+// New func have no required arguments, such as connection string.
+// Thats why we recognize that New have wrong signature.
+// Will be removed after Oct 2024.
+// Read about versioning policy: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#deprecated
+func New(ctx context.Context, opts ...Option) (_ *Driver, err error) { //nolint:nonamedreturns
 	d, err := newConnectionFromOptions(ctx, opts...)
 	if err != nil {
 		return nil, xerrors.WithStackTrace(err)

examples/topic/topicreader/topicreader_advanced.go

@@ -50,14 +50,14 @@ func UnmarshalMessageContentToOwnType(ctx context.Context, reader *topicreader.R
 // ProcessMessagesWithSyncCommit example about guarantee wait for commit accepted by server
 func ProcessMessagesWithSyncCommit(ctx context.Context, db *ydb.Driver) {
 	reader, _ := db.Topic().StartReader("consumer", nil,
-		topicoptions.WithCommitMode(topicoptions.CommitModeSync),
+		topicoptions.WithReaderCommitMode(topicoptions.CommitModeSync),
 	)
 	defer func() {
 		_ = reader.Close(ctx)
 	}()
 
 	for {
-		batch, _ := reader.ReadMessageBatch(ctx)
+		batch, _ := reader.ReadMessagesBatch(ctx)
 		processBatch(batch.Context(), batch)
 		_ = reader.Commit(ctx, batch) // will wait response about commit from server
 	}
@@ -67,7 +67,7 @@ func ProcessMessagesWithSyncCommit(ctx context.Context, db *ydb.Driver) {
 // commit messages to YDB
 func OwnReadProgressStorage(ctx context.Context, db *ydb.Driver) {
 	reader, _ := db.Topic().StartReader("consumer", topicoptions.ReadTopic("asd"),
-		topicoptions.WithGetPartitionStartOffset(
+		topicoptions.WithReaderGetPartitionStartOffset(
 			func(
 				ctx context.Context,
 				req topicoptions.GetPartitionStartOffsetRequest,
@@ -84,7 +84,7 @@ func OwnReadProgressStorage(ctx context.Context, db *ydb.Driver) {
 	)
 
 	for {
-		batch, _ := reader.ReadMessageBatch(ctx)
+		batch, _ := reader.ReadMessagesBatch(ctx)
 
 		processBatch(batch.Context(), batch)
 		_ = externalSystemCommit(

examples/topic/topicreader/topicreader_simple.go

@@ -24,7 +24,7 @@ func PrintMessageContent(ctx context.Context, reader *topicreader.Reader) {
 // ReadMessagesByBatch it is recommended way for process messages
 func ReadMessagesByBatch(ctx context.Context, reader *topicreader.Reader) {
 	for {
-		batch, _ := reader.ReadMessageBatch(ctx)
+		batch, _ := reader.ReadMessagesBatch(ctx)
 		processBatch(batch.Context(), batch)
 		_ = reader.Commit(batch.Context(), batch)
 	}