I don't recommend breaking user APIs. There are many ways we can avoid it. > 1. We should support passing the context to some IO-related methods like `Ack`, `Close`, `Flush`, etc, or any other methods. There is an issue related to this discussion. [2]
We can add a method with context, so like: CloseWithContext. > 2. Some methods need to return the error. Like `Reader.HasNext`, `Close`. This is to adhere to Golang's error-handling standards. We can still follow the above way, so like: CloseWithError. > 4. Some APIs need to be refined and require introducing breaking changes as they could affect user experience otherwise. For example, this [4] is an issue discussing the redesign of the Backoff Policy API. In the ConsumerOptions, we use the `internal` package, this is incorrect, when you set the value for `BackoffPolicy`, you will see this error `Use of the internal package is not allowed`. For internal package, please see https://go.dev/doc/go1.4#internalpackages For incorrect implementation, we can fix this. > We can provide a separate package path for v1.x API versions, maintaining v0.x and v1.x APIs separately. This will increase our maintenance times. Matteo Merli <matteo.me...@gmail.com> 于2024年3月30日周六 13:08写道： > The plan looks great. > > I’d add one more item for consideration: using WithX() methods instead of > a strict for configurations: > https://github.com/apache/pulsar-client-go/issues/68 > > > -- > Matteo Merli > <matteo.me...@gmail.com> > > > On Fri, Mar 29, 2024 at 5:38 AM Zike Yang <z...@apache.org> wrote: > > > Hi, everyone > > > > The Pulsar Go Client[0] is now relatively mature. I've also noticed > > that many people in the community have widely used it in their > > production environments. However, there's still no official 1.0 > > version for the Go client. I would like to start a thread to discuss > > the plan for releasing Go client 1.0.0. > > > > According to "Go Module version numbering" [1], there are strict > > requirements for version management in Golang projects, which means we > > can't introduce any breaking changes within a major version. Before > > releasing version 1.0.0, we need to review our API and decide on the > > finalized API for Go client 1.0.0. > > > > I've observed that the current design of the Go client's API still has > > the following issues: > > > > 1. We should support passing the context to some IO-related methods > > like `Ack`, `Close`, `Flush`, etc, or any other methods. There is an > > issue related to this discussion. [2] > > 2. Some methods need to return the error. Like `Reader.HasNext`, > > `Close`. This is to adhere to Golang's error-handling standards. > > 3. We should expose errors to users so that users can inspect the > > types of errors returned. [3] is an issue to discuss about this. > > 4. Some APIs need to be refined and require introducing breaking > > changes as they could affect user experience otherwise. For example, > > this [4] is an issue discussing the redesign of the Backoff Policy > > API. > > > > Additionally, we need to continue standardizing the release process > > and fixing known issues: > > 1. Refine the changelog formt [5]. We could try to utilize the tool > > "go-changelog" [6] to generate the changelog automatically. > > 2. Refine the release process [7] to adhere the Golang Moduel version > > standard. We need to clearly define the compatibility relationships > > between different types of versions. Some processes may need to be > > adjusted to comply with these version standards. > > > > These API changes will inevitably introduce breaking changes. However, > > we do not want the release of Go client 1.0.0 to cause troublesome > > impacts on the upgrade process for all our existing users. > > Inspired by the blog "The Principles of Versioning in Go" [8], I > > believe we need to follow this principle in the process of releasing > > 1.0.0 and also for maintaining subsequent versions: We should strive > > to avoid introducing breaking changes to the existing APIs and > > behaviors. We aim to reduce the steps needed for users to upgrade to > > the major version. > > > > To achieve this, I would like to suggest the following basic solution: > > > > We can provide a separate package path for v1.x API versions, > > maintaining v0.x and v1.x APIs separately. At the same time, we will > > deprecate all v0.x APIs. For future major versions like 2.x, 3.x, we > > will follow this same approach according to Golang's standards. In > > this way, when users upgrade to 1.0.0, they can gradually modify their > > code to utilize the new version of API, while still being able to use > > the features of the old API. We will remove the v0.x API in a later > > version, perhaps in version 2.0.0. > > > > The structure for the v1 package would look like this: > > ├── go.mod # Note: The v0 APIs and v1 APIs will shared the same go.mod > > ├── v1 > > │ └── pulsar > > │ └── client.go > > └── pulsar > > └── client.go > > > > I did a small demo. You can check it here: > > https://github.com/RobertIndie/test-go [9]. > > > > In this way, the user could still use `go get > > github.com/apache/pulsar-client-go@v1.0.0` > <http://github.com/apache/pulsar-client-go@v1.0.0> > > <http://github.com/apache/pulsar-client-go@v1.0.0> to upgrade to the > > v1.0.0 > > version. And use `import > > "github.com/apache/pulsar-client-go/v1/pulsar"` to use the new V1 API. > > And for the future major versions like v2.0.0. The users could use `go > > get github.com/apache/pulsar-client-go/v2` > <http://github.com/apache/pulsar-client-go/v2> > > <http://github.com/apache/pulsar-client-go/v2> to install the client and > > use `import "github.com/apache/pulsar-client-go/v2/pulsar` > <http://github.com/apache/pulsar-client-go/v2/pulsar> > > <http://github.com/apache/pulsar-client-go/v2/pulsar> to use the > > V2 API. > > > > While Golang's versioning standard allows us to introduce breaking > > changes to the v0.x API, I favor preserving the current API. > > Considering the resistance our users have towards upgrades, I am more > > inclined to avoid breaking changes to the existing API. This approach > > should reduce the impact of upgrades. > > > > For our next steps, we could proceed as follows: > > 1. Discuss and finalize the Go client version strategy to adhere to > > the "Golang Module version standard"[1] > > 2. Discuss and finalize the V1 API. We may need a PIP to finalize it. > > 3. Add the V1 API, develop the necessary features, and address issues > > based on this new API. > > 4. Release the Go Client 1.0.0 based on the refined release process. > > > > This is currently just a preliminary idea and plan for the release of > > Go client 1.0. I would like to hear your thoughts and ideas. > > What are your thoughts on this proposal? What else do you believe we > > need to do before releasing Go client v1.0.0? Please feel free to add > > any points I may have missed, and feel free to leave your comments > > here. > > > > Thanks, > > Zike Yang > > > > [0] https://github.com/apache/pulsar-client-go > > [1] https://go.dev/doc/modules/version-numbers > > [2] https://github.com/apache/pulsar-client-go/issues/1170 > > [3] https://github.com/apache/pulsar-client-go/issues/1142 > > [4] https://github.com/apache/pulsar-client-go/issues/1187 > > [5] https://github.com/apache/pulsar-client-go/blob/master/CHANGELOG.md > > [6] https://github.com/hashicorp/go-changelog > > [7] > > > https://github.com/apache/pulsar-client-go/blob/master/docs/release-process.md > > [8] https://research.swtch.com/vgo-principles > > [9] https://github.com/RobertIndie/test-go > > >
