Module aware generator #1436

spf13 · 2021-07-01T22:27:43Z

The cobra tool needed some extra updating to make it work seamlessly within the world of Go modules.

I've dramatically simplified it to just work within a Go module. Now within a module you can just cobra init and it works. No paths or module names required.

I've also made two additional behavioral changes:

Viper is no longer included by default. I've heard too much feedback from users that are confused by this and don't know where Cobra ends and Viper begins. Let's simplify that experience.
There is no default license. There's questionable legal ramifications with choosing a license for users without their election. Better to have them take an action to set the license.

Cobra and Viper are great together, but it's not uncommon to use them apart. New Cobra users don't know better and including Viper by default adds complexity to the skeleton.

It's questionable that a default license makes any sense from a legal perspective. If the tool created the license without the user choosing it, then it may not even be applicable. Best to let the user choose their license with intent.

CLAassistant · 2021-07-01T22:27:49Z

All committers have signed the CLA.

Pretty major change in behavior, but with modules a change is needed. Now cobra can initialize and add from within any Go module. The experience is simplified and streamlined, but requires `go mod init` to happen first.

cobra/cmd/init.go

user_guide.md

jharshman

@spf13 since the documentation is changing here could you also open a PR on https://github.com/spf13/cobra.dev if you haven't made the changes there already?

cobra/cmd/init.go

jharshman · 2021-07-02T02:02:05Z

cobra/cmd/init.go

+	return mod, dir
+}
+
+type Mod struct {


nit: can you put each of these variables on their own line?

I can. What is the motivation for doing so? (mostly just curious).

For me it's readability. I find it easier to read the structure fields when they are not condensed on one line.

jharshman · 2021-07-02T02:05:00Z

cobra/cmd/init.go

 			projectPath, err := initializeProject(args)
 			cobra.CheckErr(err)
+			cobra.CheckErr(goGet("github.com/spf13/cobra"))


I'm not sure how I feel about this utility fetching dependencies for the user. @wfernandes @jpmcb thoughts here?

I guess the point is having them explicitly added to the go.mod file of the user? Not so much about fetching them.

Yes, that is the intent. Russ Cox suggested we do this extra step and I agree. It streamlines the experience for the user as well as simplifying the instructions.

One of the motivations for this update is that we are writing a tutorial on building CLIs with Go for golang.org / go.dev which uses Cobra. As we wrote the tutorial it became clear that there were lots of places in the onboarding experience that could be streamlined. This set of changes comes from those learnings.

@spf13, in the context of writing a tutorial and streamlining the experience for newcommers, you might want to have a look at #1240. I do think that might be a very disruptive change, but at the same time it would be very valuable to have your feedback.

That is also the purpose of #1430.

See my note on #1240. I think we're likely to resolve this in the next few months by removing the need for cobra generator entirely.

As we wrote the tutorial it became clear that there were lots of places in the onboarding experience that could be streamlined.

I'm inclined to agree on this point but am always wary of tools that try to do too many things.

We can move forward with this change though.

If this is just in the cobra CLI tool, sounds good to me. I'd be more cautious of anything in the API that would automatically fetch dependencies. But it makes sense to try and streamline the onboarding experience and get people up and going with cobra init as quick as possible 👍

Merging the updated documentation from the user_guide into the cobra/README.md. Adding links as appropriate to both guides.

spf13 · 2021-07-02T15:01:18Z

@spf13 since the documentation is changing here could you also open a PR on https://github.com/spf13/cobra.dev if you haven't made the changes there already?

I'll do that as soon as this is accepted. For that, do you want a PR or for me to just make the changes directly? Happy to do either.

umarcor · 2021-07-02T15:24:59Z

cobra/README.md

@@ -3,41 +3,78 @@
 Cobra provides its own program that will create your application and add any
 commands you want. It's the easiest way to incorporate Cobra into your application.

-In order to use the cobra command, compile it using the following command:
+Install the cobra generator with the command `go install github.com/spf13/cobra/cobra`. 


In CI, we are currently using GOBIN (see https://github.com/spf13/cobra/blob/master/.github/workflows/Test.yml). Might be worth adding a reference to https://golang.org/cmd/go/#hdr-Compile_and_install_packages_and_dependencies here?

jharshman · 2021-07-07T15:35:10Z

@spf13

I'll do that as soon as this is accepted. For that, do you want a PR or for me to just make the changes directly? Happy to do either.

Yes please PR it.

jharshman

@spf13 are you ready for this to be merged?

spf13 · 2021-07-21T13:49:08Z

I still need to write up the PR for the doc site. I've been swamped with other stuff. I think that's all this is waiting on. It will be a couple weeks before I'll be able to get to it. I'm fine if anyone else wants to do that and merge this, but realistically speaking I'll be a couple weeks before I can.

…

On Wed, Jul 21, 2021 at 12:03 AM Joshua Harshman ***@***.***> wrote: ***@***.**** approved this pull request. @spf13 <https://github.com/spf13> are you ready for this to be merged? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1436 (review)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABKKZB2XQIAKJKKPIALHRLTYZBJPANCNFSM47VSJ6RA> .

jpmcb

Sorry for being late to this one - this looks good to me and I think will be a welcome change since most everyone should be on go modules by now! 🚀

github-actions · 2021-10-04T00:04:51Z

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

spf13 · 2021-10-05T02:06:52Z

I'll try to get to this in the next week or two. Bumping so it's not stale anymore.

cobra/README.md

spf13 added 3 commits July 1, 2021 17:16

Removing unused imports when not using Viper

d225ba8

Change generator to require opting in to viper.

0243fe0

Cobra and Viper are great together, but it's not uncommon to use them apart. New Cobra users don't know better and including Viper by default adds complexity to the skeleton.

Change generator default license to none

0463683

It's questionable that a default license makes any sense from a legal perspective. If the tool created the license without the user choosing it, then it may not even be applicable. Best to let the user choose their license with intent.

spf13 requested review from wfernandes, jharshman and jpmcb July 1, 2021 22:27

github-actions bot added the area/cli [deprecated] For the cobra CLI !!! moved to spf13/cobra-cli label Jul 1, 2021

spf13 added 2 commits July 1, 2021 18:38

Cobra generator now works within Go modules

25ac916

Pretty major change in behavior, but with modules a change is needed. Now cobra can initialize and add from within any Go module. The experience is simplified and streamlined, but requires `go mod init` to happen first.

Update documentation to reflect the module aware generator

d7b9dc5

spf13 force-pushed the module-aware-generator branch from c06749d to d7b9dc5 Compare July 1, 2021 22:38

umarcor reviewed Jul 2, 2021

View reviewed changes

cobra/cmd/init.go Show resolved Hide resolved

cobra/cmd/init.go Outdated Show resolved Hide resolved

user_guide.md Outdated Show resolved Hide resolved

jharshman reviewed Jul 2, 2021

View reviewed changes

Updating generator documentation and links

b4ab663

Merging the updated documentation from the user_guide into the cobra/README.md. Adding links as appropriate to both guides.

Simplifying goGet function

31a1f21

umarcor reviewed Jul 2, 2021

View reviewed changes

jharshman approved these changes Jul 21, 2021

View reviewed changes

jpmcb approved these changes Aug 4, 2021

View reviewed changes

github-actions bot added the kind/stale label Oct 4, 2021

marckhouzam reviewed Oct 5, 2021

View reviewed changes

cobra/README.md Outdated Show resolved Hide resolved

marckhouzam reviewed Oct 5, 2021

View reviewed changes

cobra/README.md Outdated Show resolved Hide resolved

marckhouzam reviewed Oct 5, 2021

View reviewed changes

cobra/README.md Outdated Show resolved Hide resolved

marckhouzam reviewed Oct 5, 2021

View reviewed changes

cobra/README.md Outdated Show resolved Hide resolved

cobra/README.md Outdated Show resolved Hide resolved

Addressing typos identified by @marckhouzam

b33fae1

spf13 merged commit bfacc59 into master Nov 3, 2021

jpmcb deleted the module-aware-generator branch October 24, 2022 15:58

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Module aware generator #1436

Module aware generator #1436

spf13 commented Jul 1, 2021

CLAassistant commented Jul 1, 2021 •

edited

jharshman left a comment

jharshman Jul 2, 2021

spf13 Jul 2, 2021

jharshman Jul 7, 2021

jharshman Jul 2, 2021

umarcor Jul 2, 2021

spf13 Jul 2, 2021

spf13 Jul 2, 2021

umarcor Jul 2, 2021 •

edited

spf13 Jul 2, 2021

jharshman Jul 7, 2021

jharshman Jul 7, 2021

jpmcb Aug 4, 2021

spf13 commented Jul 2, 2021

umarcor Jul 2, 2021

spf13 Jul 2, 2021

jharshman commented Jul 7, 2021

jharshman left a comment

spf13 commented Jul 21, 2021 via email

jpmcb left a comment

github-actions bot commented Oct 4, 2021

spf13 commented Oct 5, 2021

Module aware generator #1436

Module aware generator #1436

Conversation

spf13 commented Jul 1, 2021

CLAassistant commented Jul 1, 2021 • edited

jharshman left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

umarcor Jul 2, 2021 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

spf13 commented Jul 2, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jharshman commented Jul 7, 2021

jharshman left a comment

Choose a reason for hiding this comment

spf13 commented Jul 21, 2021 via email

jpmcb left a comment

Choose a reason for hiding this comment

github-actions bot commented Oct 4, 2021

spf13 commented Oct 5, 2021

CLAassistant commented Jul 1, 2021 •

edited

umarcor Jul 2, 2021 •

edited