Use semantic versioning

[onlyjob]

Please consider assigning version numbers and tagging releases. Tags/releases
are useful for downstream package maintainers (in Debian and other distributions) to export source tarballs, automatically track new releases and to declare dependencies between packages. Read more in the Debian Upstream Guide.

Versioning provides additional benefits to encourage vendoring of a particular (e.g. latest stable) release contrary to random unreleased snapshots.

Thank you.

See also

• http://semver.org/
• https://en.wikipedia.org/wiki/Software_versioning

[mattfarina]

I'd like to second this request. It would allows tools like Glide to find and use release versions.

[YvanDaSilva]

Just like on your other tool: spf13/viper#173
I heavily suggest you do a repository release.

Many tools out there have this requirements, and go team and all those tools creators are looking into a way to handle vendoring properly.
And the git rev in the language is already out of question.

I highly advice the reading of the following posts.
http://dave.cheney.net/2016/06/24/gophers-please-tag-your-releases
http://dave.cheney.net/2016/06/26/automatically-fetch-your-projects-dependencies-with-gb

[klauern]

I don't like to pile on, but since the dep tool that is being developed relies on tagged releases, I would like there to be something official in terms of a 1.x release to stay compatible with that tool and possibly for future-proofing this repo when that is finalized.

[vividvilla]

As others have enforced in this thread with the advent of vendoring tools like dep and glide it makes more sense to maintain semantic release versions. Hope the author will consider it soon.

[rv-rsouza]

This is a mandatory "feature" to allow version locking with dependency managers.
Please consider adding this, as it is easy to do and can be done with git command line or directly on GitHub.

Don't let this idea die!
Thanks for this awesome work. It just deserves a bit more attention.

[zevdg]

It seems like this is the correct place to continue the discussion from #519 on dep adoption.

Not only should cobra tag a release to play nicely with clients using dep, but IMO it should also adopt dep itself. Effectively, this just means checking in a Gopkg.toml and a Gopkg.lock file and deciding whether to commit the vendor directory or not. Since this project has never adopted vendoring in the first place, adding vendor to .gitignore would be the least disruptive choice. There are pros and cons worth considering for each approach.

[bpicode]

I also opt for not checking in the vendor folder.

Libraries should never vendor their dependencies.
https://peter.bourgon.org/go-best-practices-2016/#dependency-management

The pros aren't really that great for cobra,

• "dep ensure on fresh clones": isn't a problem IMO
• "reproducible builds": is the responsibility of downstream users.

[mattfarina]

@bpicode The problem with not checking in vendor is that the install instructions say to use go get -u github.com/spf13/cobra/cobra. This will cause the tip of master on dependencies to be fetched into the GOPATH instead of using the revisions in the Gopkg.lock.

[bpicode]

@mattfarina You're right, I see your point. Cobra is somewhat special since it is both a library as well as a client of itself. I was somewhat biased, prioritizing the library aspect.

[rv-rsouza]

Of course, if you move to using dep or glide you could change the install instructions accordingly and add the package manager as requirement.

[zevdg]

Not really. dep still encourages go get for installing tools like cobra's cli. I'd love for a hypothetical dep install to exist that would get the lastest semver release, resolve dependencies using the lockfile, and then go install the resulting binary, but alas no such thing exists. If you want to use dep as part of your installation procedure, it suddenly makes the tool very hard to install. Something along the lines of

go get <import path>
cd $GOPATH/src/<import path>
git checkout <latest release tag>
dep ensure
go install

The only option for a cli tool to yield a great install experience through go get is to

1. make sure master is always pointing to the latest semver release by doing most development on other branches
2. check in the vendor folder

Only if you do both of those things will go get do the "right" thing of installing the latest tagged release with a repeatable build. That said, not even dep itself does the first of these 2 things and they encourage you to use go get to install their tool. I guess they don't mind that people are using versions that aren't tagged releases, so I don't think there is a best practice to follow here yet.

[zevdg]

Also, dep definitely deletes the vendor directory out of dependency projects, so if cobra were to check in its vendor folder, downstream clients of the library using dep would not be affected by this (apart from slightly slower git clones). It's downstream clients who have not yet adopted dep that would potentially be affected if cobra were to check in a vendor folder at the root of its project.

What would really be ideal is for a vendor folder to be checked in not at the root of the repository but inside the cobra sub directory. Then go get would use the vendor directory when compiling the cli tool, but not when pulling in the library. I've never used dep on more than one package in the same repo before, but in theory it seems to work. See #523 for what this would potentially look like.

[peterbourgon]

Please tag a release using semantic versioning. Even something as simple as assigning v0.0.1 to the current master would be greatly beneficial to tools like dep.

[n10v]

@peterbourgon done

[jpignata]

Request: any chance of bundling the latest master into a release before the 2.0.0 milestone? I'd like to move my project to dep, but I use cobra's version flag facility which doesn't exist in the release marked v0.0.1. 🙇 Thanks!

[jpignata]

Any chance of cutting a new release (0.0.2 perhaps)? I'd really like to incorporate dep for dependency management and this is blocking that. Sorry to nag - just checking to see if I should find another path.

[alexejk]

While I would agree with you that it would make sense to get some more releases out - you can use either branch = "master" or even lock a specific commit in the [[ constraint ]] sections with dep. This is what we are doing anyways.

[jpignata]

@alexejk Fair enough. I'll lock to a commit for now - thanks!

[mattfarina]

When using it as a library, as most are, you need to lock to something instead of pulling from master. If you check in the dependency to your repo you are locking to version there (and should have that recorded somewhere). If you go get and use CI systems then you could end up with different versions in dev, test, and prod.

What versions get you is a point where it's marked as stable and semantic versions get you things marked as stable with different kinds of intent (patch fix, new features, api breaking change).

Use of SemVer is really about communicating intent to those consuming it. That's why I ask you to do it.

[alexejk]

@mattfarina this does make sense as per my comment above, but it also is the fact that while it's not as convenient - you can lock to a specific commit which effectively gives you the same thing as locking to a version.

Version releases quite often mean that this is a complete iteration (no matter what "level" of iteration) while commit will effectively give you a snapshot in time. If e.g current master is stable and good enough for you - take it's commit hash and lock to it while the author takes the time needed to feel comfortable with the next release.

Instructions could be updated, and if you are using e.g dep then simply make sure to commit your Gopkg.lock (along side the Gopkg.toml) to ensure reproducibility. As a matter of fact, if you commit those two files and run dep ensure -vendor-only you will actually only read from the lock file, including exact commit (even if the constraint was set to branch = "master".

So I would argue that the issue is mainly instructions / setup on some systems that blindly dogo get instead of using e.g dep.

The above doesn't change the point of me being all in favor of semver releases for this and all other projects we depend on, but it means that while it's not as convenient - even without semver you can get the same benefits of locking down (you do loose quick understanding which level of impact an update gives, as this is the biggest benefit of semver).

P.S.: Maybe current state isn't "ready" to be even 0.0.2 as it's WIP ;-)

[zevdg]

Just to add on to what @alexejk said. Even without the -vendor-only flag, dep will not change the version in the lock file unless you ask it to or it absolutely has to (e.g. some other library got pulled in that requires a newer version of the "locked" dependency). Locking to specific commits in your manifest is unnecessary and harmful. That is the whole point of the lockfile. Trust the lockfile.

Almost everyone who is thinking about locking to a specific commit in their manifest because they need something that isn't in a server tagged release should instead:

1. Use a branch = "master" constraint in your manifest (or whatever branch you need)
2. Check in your Gopkg.lock file
3. Use dep normally and simply review changes in the lockfile when they happen.

That's it. For most small projects, this is sufficient.

If you have automated builds, then you could use the -vendor-only flag to ignore the manifest, but that could result in "successful" builds that are inconsistent with the constraints in the manifest and/or source code (e.g. someone changed dependencies but forgot to update or check in their lockfile). Instead, I'd recommend starting your automated build script with dep ensure -no-vendor -dry-run (more info) to make your build fail ASAP when things are fishy.

[peterbourgon]

And just to zoom out on the broader discussion: we could largely bypass all of this needless specificity if spf13/cobra would simply tag releases on a regular cadence. It's totally bizarre to me that a project with so many users is so resistant to this...

[bweston92]

Could really do with another release that means I don't need to pin "master" just to get "--version" support.

[rawtaz]

To the project owners; So many people are asking for tagging new versions/releases - why are you so reluctant to do that? Just tag v0.0.2 and everyone will be happy. What is stopping you?

[peterbourgon]

I think the problem is that nobody is really the project owner here. @spf13 can you nominate someone?

[broady]

@eparis is the owner, but I also have access and will tag it if @eparis doesn't pick it up.

[broady]

Over a week has passed, so I'll take @eparis's silence as a 👍to proceed.

0.0.2 is tagged.

If you want another tag in the future, reply here and/or @/DM me on Twitter: @broady.

Also, I noticed that @BoGeM said "Normal semantic versioning will be introduced in 2.0.0."
This seems wrong, cobra is already using "normal semantic versioning" - 0.x means pre-release. And I would expect the first "major" release to be 1.0.0, not 2.0.0.

[ncw]

Please can we have another release @broady ? The last tagged version is 0.0.3 May 15, 2018 and that is what all go mod users will be picking up by default. Thanks

 $ grep cobra go.mod 
	github.com/spf13/cobra v0.0.3

[marckhouzam]

Hi @broady, the last Cobra release dates back to a year ago. There has been a couple of fixes that have value. Specifically, #730 is particularly important as it fixes a collision between different cobra apps that perform custom completion.

I'm working on adding custom completion to the Helm project (for the v3 release) but without #730 I cannot add it as it will likely break custom completion for kubectl. In fact, without #730 kubectl custom-completion is vulnerable to any other cobra app breaking it.

I tried to simply use the latest Cobra commit, but transitive dependencies of other projects are locked to a tagged releases of Cobra.

Would it be possible to make a 0.0.4 release to make the Cobra fixes of the last year available?

Thank you for considering it.

[broady]

@eparis, are you up for tagging? Happy to do this when people message me to ask.

Will tag 0.0.4 if I don't hear back in a few days.

[umarcor]

@broady, would you please consider merging #817 either before or just after tagging 0.0.4? @jharshman has been keeping it up to date during the last months and it is a very demanded feature.

[marckhouzam]

@broady ping :-)

[broady]

Sorry, I don't know the codebase well enough to do a proper review of that.

Tagging 0.0.4 right now.

[broady]

Done. See all changes between 0.0.3 and 0.0.4:
v0.0.3...v0.0.4