TL;DR:

The introduced /api sub-module makes vendoring for depending parties unnecessarily complex and there is no easy way to improve this situation. Therefore, I propose to remove the sub-module again and instead work with one and simple module.

Describe the bug:
#169 added a nested sub-module api to etcd-druid in order to make dependency management more efficient.

After experiencing with this approach the opposite turned out.

At the moment, components depending on github.com/gardener/etcd-druid/api need to maintain their go.mod file as the following:

require (
        ...
	github.com/gardener/etcd-druid/api v0.0.0-00010101000000-000000000000
        ...
)

replace (
        ...
	github.com/gardener/etcd-druid => github.com/gardener/etcd-druid v0.6.0
	github.com/gardener/etcd-druid/api => github.com/gardener/etcd-druid/api v0.6.1-0.20211011084637-5c908089a872
        ...
)

Please note, in case etcd-druid is a transient dependency, the replace configuration must be added again because it's not automatically taken over from the direct dependency.

Why it is not possible to depend on an API sub-module version directly:

require (
        ...
	github.com/gardener/etcd-druid/api v0.6.1-0.20211011084637-5c908089a872
        ...
)

The configuration above will lead to an ambiguous import error. There are versions (< v0.6.0) which only contain one module (with /api/... packages inside) and versions (>= v0.6.0) that serve /api as a sub-module.
Adding a sub-module to an existing repository with earlier releases implies extra actions that have not been tackled yet - see here for more information.

In addition, there is the complexity that the outer module has a dependency to the inner /api module and because we don't want to maintain pre-release tags locally, we work with the pseudo version v0.0.0-00010101000000-000000000000. So, even if we tackled the missing actions mentioned above, the depending parties still have to configure their replace directives accordingly because the pseudo version v0.0.0-00010101000000-000000000000 is not resolvable.

	github.com/gardener/etcd-druid@v0.6.0 requires
	github.com/gardener/etcd-druid/api@v0.0.0-00010101000000-000000000000: invalid version: unknown revision 000000000000

We needed to add some cyclic dependency procedure to our development and release flow in order to solve this issue as well (see this comment).

For the mentioned reasons, we better remove the /api sub-module again and instead have one simple module as it was the case before v0.6.0. The advantage of having a separate and nested-module is entirely eliminated by the complexity and problems it entails.

Expected behavior:
Modules having a (direct or indirect) dependency to https://github.com/gardener/etcd-druid should not need to configure replace directives in their go.mod files.

/area dev-productivity
/cc @abdasgupta @shreyas-s-rao @timebertt @plkokanov