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` 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` to install the client and
use `import "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
