Use gorelease to check compatibility of controller-runtime

[liubog2008]

My project import may operator project modules and they all depend on controller-runtime but with different versions.
There are many compatibility problems when upgrade controller-runtime.

How about add gorelease tool in CI to check compatibility issue when release a new version.

[troy0820]

/kind support

[sbueringer]

@liubog2008 Can you explain how the gorelease tool would improve the current state?

[liubog2008]

There are many incompatible changes between two versions of controller-runtime. For example, I find that many fields in manager.Options are deleted. In fact, it breaks the compatibility of this module.
The go module uses semver to judge whether the two versions are compatible and will auto select the newer one if two version are compatible.
gorelease will check whether a change breaks the compatibility. It can be added into CI workflow.

[liubog2008]

A example to run gorelease for controller-runtime

gorelease -base=v0.15.0 -version=v0.16.0
# sigs.k8s.io/controller-runtime
## incompatible changes
SchemeBuilder: changed from sigs.k8s.io/controller-runtime/pkg/scheme.Builder to sigs.k8s.io/controller-runtime/pkg/builder.Builder

# sigs.k8s.io/controller-runtime/pkg/cache
## incompatible changes
Informers.GetInformer: changed from func(context.Context, sigs.k8s.io/controller-runtime/pkg/client.Object) (Informer, error) to func(context.Context, sigs.k8s.io/controller-runtime/pkg/client.Object, ...InformerGetOption) (Informer, error)
Informers.GetInformerForKind: changed from func(context.Context, k8s.io/apimachinery/pkg/runtime/schema.GroupVersionKind) (Informer, error) to func(context.Context, k8s.io/apimachinery/pkg/runtime/schema.GroupVersionKind, ...InformerGetOption) (Informer, error)
MultiNamespacedCacheBuilder: removed
Options.Namespaces: removed
Options.UnsafeDisableDeepCopy: removed
## compatible changes
AllNamespaces: added
BlockUntilSynced: added
ByObject.Namespaces: added
Config: added
ErrResourceNotCached: added
InformerGetOption: added
InformerGetOptions: added
Options.DefaultNamespaces: added
Options.DefaultUnsafeDisableDeepCopy: added
Options.ReaderFailOnMissingInformer: added

# sigs.k8s.io/controller-runtime/pkg/cache/informertest
## incompatible changes
(*FakeInformers).FakeInformerFor: changed from func(k8s.io/apimachinery/pkg/runtime.Object) (*sigs.k8s.io/controller-runtime/pkg/controller/controllertest.FakeInformer, error) to func(context.Context, sigs.k8s.io/controller-runtime/pkg/client.Object) (*sigs.k8s.io/controller-runtime/pkg/controller/controllertest.FakeInformer, error)
(*FakeInformers).GetInformer: changed from func(context.Context, sigs.k8s.io/controller-runtime/pkg/client.Object) (sigs.k8s.io/controller-runtime/pkg/cache.Informer, error) to func(context.Context, sigs.k8s.io/controller-runtime/pkg/client.Object, ...sigs.k8s.io/controller-runtime/pkg/cache.InformerGetOption) (sigs.k8s.io/controller-runtime/pkg/cache.Informer, error)
(*FakeInformers).GetInformerForKind: changed from func(context.Context, k8s.io/apimachinery/pkg/runtime/schema.GroupVersionKind) (sigs.k8s.io/controller-runtime/pkg/cache.Informer, error) to func(context.Context, k8s.io/apimachinery/pkg/runtime/schema.GroupVersionKind, ...sigs.k8s.io/controller-runtime/pkg/cache.InformerGetOption) (sigs.k8s.io/controller-runtime/pkg/cache.Informer, error)

# sigs.k8s.io/controller-runtime/pkg/client/apiutil
## compatible changes
ErrResourceDiscoveryFailed: added

# sigs.k8s.io/controller-runtime/pkg/client/fake
## incompatible changes
NewFakeClientWithScheme: removed

# sigs.k8s.io/controller-runtime/pkg/cluster
## incompatible changes
Options.ClientDisableCacheFor: removed
Options.DryRunClient: removed
Options.Namespace: removed

# sigs.k8s.io/controller-runtime/pkg/controller/controllerutil
## incompatible changes
Object: removed

# sigs.k8s.io/controller-runtime/pkg/envtest
## incompatible changes
Environment.KubeAPIServerFlags: removed

# sigs.k8s.io/controller-runtime/pkg/log/zap
## incompatible changes
Options.DestWritter: removed

# sigs.k8s.io/controller-runtime/pkg/manager
## incompatible changes
Manager.AddMetricsExtraHandler: removed
Options.CertDir: removed
Options.ClientDisableCacheFor: removed
Options.DryRunClient: removed
Options.Host: removed
Options.MetricsBindAddress: removed
Options.Namespace: removed
Options.Port: removed
Options.SyncPeriod: removed
Options.TLSOpts: removed
## compatible changes
Options.Metrics: added

# sigs.k8s.io/controller-runtime/pkg/metrics
## incompatible changes
DefaultBindAddress: removed
NewListener: removed

# sigs.k8s.io/controller-runtime/pkg/metrics/filters
## compatible changes
package added

# sigs.k8s.io/controller-runtime/pkg/metrics/server
## compatible changes
package added

# sigs.k8s.io/controller-runtime/pkg/webhook
## incompatible changes
Options.TLSMinVersion: removed

# summary
v0.16.0 is not a valid semantic version for this release.
version v0.16.0 already exists

[liubog2008]

If I import a module xx requires 0.15.0 of controller-runtime and another module yy requires 0.16.0, I may have no way to resolve build conflict until xx upgrade the controller-runtime to 0.16.0.

And If we can run gorelease in CI, we can revert incompatible changes before we release a new version.

For example, we can only mark fields in Options as deprecated and remove them until a new major version is released.

[troy0820]

There are many incompatible changes between two versions of controller-runtime. For example, I find that many fields in manager.Options are deleted. In fact, it breaks the compatibility of this module.
The go module uses semver to judge whether the two versions are compatible and will auto select the newer one if two version are compatible.
gorelease will check whether a change breaks the compatibility. It can be added into CI workflow.

I think that is to suggest that controller-runtime must be backwards compatible.

Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable. Version 1.0.0 defines the public API. The way in which the version number is incremented after this release is dependent on this public API and how it changes.

Because it is at v0.x.x, there is no binding contract for backwards compatibility. The fallout from < v0.15 -> v0.15 stated in the release notes that it is a breaking change. From a semver point a view, that would institute a new major version.

While I understand what gorelease offers, it doesn't seem like it goes along with the tenants of how development and how providing an api, that can be subject to change, will be able to utilize this tooling to make release decisions.

[liubog2008]

What I complained is not controller-runtime breaks compatibility in 0.x.y version but compatibility issues are too many...
This project has been widely used, any plan to be upgraded to 1.x.y?

[troy0820]

What I complained is not controller-runtime breaks compatibility in 0.x.y version but compatibility issues are too many...
This project has been widely used, any plan to be upgraded to 1.x.y?

Understandably so, the differences between minor versions still abide by semver’s policy. The tool you are suggesting will not do anything to prevent what goes in one release minor to the next.
There has been some that stay on a particular version until the need to migrate forces the consumer to do so. However, some components use upstream k8s dependencies which minor versions upgrade at their release minor cadence. I am not a maintainer but asking for smaller breaking changes halts the development of controller runtime of what we can improve and put into a release going forward.

[liubog2008]

I find there was a issue mentioned gorelease. I'll close this one.

See #2327