Reorganise the cobra library and the CLI as siblings

[umarcor]

As discussed in #1233, having the library and the CLI reorganised as siblings in this repo would allow having separated go.mod files, while avoiding the ambiguity. However, that's a very disruptive breaking change, as the import path would probably change for all users. Hence, this issue is just a placeholder for now.

Ref #1215 #1219

[jpmcb]

I believe the problem is deeper than simply having people upgrade import paths.

Since this repo was an early adopter of go mod, the go.mod file itself has fallen a bit behind the current go mod V2 standard. Specifically:

The recommended strategy is to develop v2+ modules in a directory named after the major version suffix.

github.com/googleapis/gax-go @ master branch
/go.mod    → module github.com/googleapis/gax-go
/v2/go.mod → module github.com/googleapis/gax-go/v2

This approach is compatible with tools that aren't aware of modules: file paths within the repository match the paths expected by go get in GOPATH mode. This strategy also allows all major versions to be developed together in different directories.

Reference

Unless we completely overhaul the structure of the repo (which I think could be warranted given how far the go mod has diverted), I think we will continue to see issues related to go paths and this project.

[umarcor]

@jpmcb, IMHO, the concern you raised is legit, but unrelated to this issue. ATM, the cobra CLI tool is a child of the cobra library. That is, subdir cobra is not explicitly ignored when users import the library. That is unfortunate, because the library does not depend on that subdir at all; but it comes with a non-negligible list of extra dependencies. My understanding is that the most idiomatic solution is to make the library be the child (that is, invert the locations), or to maintain both subprojects as siblings (which I think is desirable).

Whether the go.mod file(s) are updated to the standard, that's a related but independent question. As such, it might be addressed either before or after resolving this issue.

[github-actions]

This issue is being marked as stale due to a long period of inactivity

[umarcor]

Still relevant.

[jxsl13]

bump.

[jpmcb]

We'll plan on doing this in the next release. But we should think deeply about how we want to go about this to prevent another critical regression the last time this was attempted: #1233

[umarcor]

From #1233 (comment):

1. Create spf13/cobra-cli, and move the CLI there.
2. Create org cobra and move cobra/lib, cobra/cobra, cobra/cli, whatever.
3. Move the current content in the root of this repo (except subdir 'cobra') to a new subdir (say 'lib'). Probably rename 'cobra' to 'cli'.

All options except the first one are quite disruptive because all users would need to update the import path: s#github.com/spf13/cobra#"cobra" github.com/spf13/cobra/lib#.

OTOH, creating organisation cobra might make it easier to handle three repos (cli, lib and site) while being a good excuse for the renaming.

[spf13]

The advantage of keeping the tool with the library is they will always be in sync. I'm not opposed to moving it to another repo though, just acknowledging there will be additional coordination.

We've not yet talked about it publicly much, but there's intent to develop a quickstart tool for Go and Cobra's an obvious case to build it around since there's already a prototype here. I think it's best to leave things as they are for now with hopes that the new go quickstart (or whatever we end up calling it) will displace the cobra tool entirely anyway. Let's circle back on this in a couple months when we've made more progress towards that tool. Right now it's mostly an idea without a proposal.

I strongly don't want to do anything to affect the current import path of github.com/spf13/cobra. It's used far to broadly for anything to justify this huge disruption.

[ash2k]

# on master:
go list -m all | wc -l
     151
# with cobra directory deleted
go list -m all | wc -l
       9
# with doc directory deleted
go list -m all | wc -l
       3

I think I'll use my fork for now.

[umarcor]

The advantage of keeping the tool with the library is they will always be in sync. I'm not opposed to moving it to another repo though, just acknowledging there will be additional coordination.

Agree. My preferred solution would be using subdirs in this repo:

• lib (incl. lib/doc, maybe renamed to lib/docgen): the current root with a minimal go.mod.
• cobra (or cli): the CLI tool with an extended go.mod.
• site: the documentation site with all the markdown sources. Preferredly, an Hugo site published in cobra.dev.

[liggitt]

I strongly don't want to do anything to affect the current import path of github.com/spf13/cobra. It's used far to broadly for anything to justify this huge disruption.

I strongly agree with that.

Limiting changes to the github.com/spf13/cobra/cobra/... packages seems far more tractable based on usage:

• https://grep.app/search?q=%22github.com/spf13/cobra/cobra%22 (5 public references)
• https://grep.app/search?q=%22github.com/spf13/cobra/cobra/cmd%22 (0 public references outside of vendored copies of github.com/spf13/cobra)
• https://grep.app/search?q=%22github.com/spf13/cobra/cobra/tpl%22 (0 public references outside of vendored copies of github.com/spf13/cobra)

Those packages could either be isolated (with a nested go.mod file providing a github.com/spf13/cobra/cobra module) or relocated to a different repo

[liggitt]

I opened #1597 as a proposal for splitting the modules again in a way that avoids the problems of #1139

[jpmcb]

Let's focus on #1597 - This issue is a bit stale and I think the proposal outlined in #1597 is a great place to kickoff this work.