Cli: maint: release 2.X

[lynncyrin]

If anyone is interested in the work of merging the master branch into v2, add let us know here with a _"🤚I'm interested in working on this"_ comment!

---

The comments below describe a random assortment of release 2.X concerns 📝

[lynncyrin]

I'm thinking that I'll keep the current 2.0 branch as release 2.0 forever, and the very next release I make will be 2.1.

[lynncyrin]

I'm also going to try to merge 2.0 into master ASAP. I may keep maintaining a 1.0 branch with bugfixes? If people are interested in that.

[AudriusButkevicius]

Isn't that a breaking change in terms of API? I am not sure its cool everyone that don't do vendoring. Also, current api and implementation is battle tested, v2 is not.

[lynncyrin]

Isn't that a breaking change in terms of API? I am not sure its cool everyone that don't do vendoring.

My understanding of the go community is that the vast majority of people install from a tag, eg. 1.2.4 - and don't install from the default branch, eg master. So there's no API compatibility guarantee around the master branch.

That said, I just checked the yaml package and apparently they changed their default branch to be v2 https://github.com/go-yaml/yaml. So that may be the way to go here.

Also, current api and implementation is battle tested, v2 is not.

That's true! Are you suggesting we have a beta release period, or similar?

[lynncyrin]

Got a comment via Stephen Houston in the gophers general channel on slack

Traditionally I would say you keep master based off your current stable with bugfixes added in to prepare for point releases ... I.e. if your current stable is 1.0 ... master is on 1.0 but with bugfixes added in to be able to tag 1.1 etc... you have a develop branch that is for features/future releases... when you get ready to do a new major release, i.e. v1 -> v2... master becomes develop and you tag... and then master follows 2.0 and gets bugfixes for 2.0 in order to do point releases 2.1 etc... and develop moves on to new features/future releases.

[lynncyrin]

to echo @tsingson's comment here

this gopkg.in/urfave/cli.v2 is working fine for me in product about half year.

https://github.com/urfave/cli/issues/824#issuecomment-517824045

[lynncyrin]

There's some really good discussion in this thread about go packaging and release a V2 https://github.com/urfave/cli/pull/840#discussion_r310750414

[AudriusButkevicius]

I am not sure what the plan is here.
I am not a fan of the current "there are two different incarnations of the library in a single repo" stuff.

Ideally we'd have only one library that is the right library for everyone, and that would be on master.

[marwan-at-work]

Right, eventually (and hopefully sooner rather than later) the v2 branch should be merged into master branch.

But note that Go Modules completely doesn't care about either branches when you have git tags that are proper semver (which we do)

So my suggestion is the following:

you add a go.mod to the master branch with the following header module github.com/urfave/cli and then creating a new git tag: v1.22.0

and this way anyone issuing a go get github.com/urfave/cli will get the latest version (v1.22.0).

If someone wanted to get a version not yet tagged, they can still do go get github.com/urfave/cli@master and that should still work.

Now, once we merge v2 into master, anyone trying to do go get github.com/urfave/cli@master should fail since v2 is the default master branch and v2 is by definition a breaking change. I think that's totally okay, because anyone still wanting to get the regular v1 even after we merge v2 into master, can still do go get github.com/urfave/cli@latest or go get github.com/urfave/cli or even go get github.com/urfave/[email protected] (x being whatever number they wish)

Furthermore, once we have v2 merged into master, we need to tag a new release, probably v2.0.0. But we MUST change the go.mod file BEFORE we tag the new release to be module github.com/urfave/cli/v2 so that we maintain semantic import versioning.

And finally, everything should work. The master is the latest v2 version (which is what you suggested above), people can remain to use v1 as they wish (because Go Modules uses regular semver tags, and doesn't care about what's in the master branch). and people can also use v2 through the import path itself since it will have a v2 suffix.

The only thing missing in this process is patch branches, which we can create on the fly (if we know the exact commit before a major bump in master), or we can create stale version branches.

[lynncyrin]

I am not a fan of the current "there are two different incarnations of the library in a single repo" stuff.

I agree 👍

[AudriusButkevicius]

Now, once we merge v2 into master, anyone trying to do go get github.com/urfave/cli@master should fail since v2 is the default master branch

Presumably this requires go.mod to be updated with a /v2 suffix?
I guess go get github.com/urfave/cli with go version prior to module support would fetch v2 by default?

[marwan-at-work]

@AudriusButkevicius

Presumably this requires go.mod to be updated with a /v2 suffix?

Yes, and also because I imagine the v2 has a different API than v1. Otherwise it wouldn't be v2, it would just be v1.x.x.

I guess go get github.com/urfave/cli with go version prior to module support would fetch v2 by default?

Yes, but since urfave/cli does not have sub-packages that it imports, it should continue to work. Though I'd be a fan of telling users to use modules if they want to use v2 since it'll be the default convention in 1.14 and onwards.

[AudriusButkevicius]

Seems like we're ok to merge v2 into master then.
I guess we need to compare feature parity and make sure we are happy with the API before we do that.

[lynncyrin]

In case it's not clear - we will make explicitly sure that V2 has all the same features that V1 has currently 🙂

[AudriusButkevicius]

I haven't really checked what v2 actually looks like. Was it forked or rewritten? Is anyone aware of things that are missing in v1 but not v2 and vica versa?

[lynncyrin]

For my part, I also don't know anything about the current status of V2

[lynncyrin]

👋 I updated the first post in this issue to reflect that fact that I specifically am not working on V2 right this moment. If anyone wants to do the work of bringing V2 up to date, let us know here!

[asahasrabuddhe]

I think merging master with v2 is going to be fun. Aside from bringing over features and bugfixes to v2, I think the two things we should consider for v2 are:

1 Getting rid of altsrc and merging the functionality into the main package
2 Restructuring the codebase to reduce the large number of files in the repo root. I thoroughly agree with @AudriusButkevicius about the need of having to clean the chaos.

I think if we can agree on this, I'd like to take this up and move forward toward a stable release. In the coming months, I'd really like to see everyone working on v2 :)

[lynncyrin]

Since V2 has been around for quite some time, I would slightly prefer if we made those additional breaking changes in V3? I'm fine adding them to V2 if enough people want that though!

[asahasrabuddhe]

What we can do in v2 is do the necessary refactors and still keep the existing public API using referencing our new internal API.

For v3, we can clean that up and have a brand new API

I think the more we push this back, the longer and more difficult the transition is going to be. I think we should have a date in mind and then only add new features to v2 and backport necessary features based on a vote. Otherwise, we would keep on maintaining multiple versions for a long time

[lynncyrin]

Yea I want to get V2 into master ASAP, and ideally only backport bug fixes.

[asahasrabuddhe]

Let me get this underway from coming Monday

[lynncyrin]

@asahasrabuddhe can I assign you to working _only on merging V2 into master_ and (temporarily) un-assign you from the other tasks?

If you put up a draft PR for that work and only work inside of that PR, I can start getting a good idea of where we'll get merge conflicts and start moving all the other existing feature proposals over to V2.

In other words: I would like to help "clear the field" so that V2 can land into master cleanly 🙂

[asahasrabuddhe]

@lynncyrin yes please. I'd like that very much

[asahasrabuddhe]

Most of the changes done to v2 can be found in the CHANGELOG.md. However, for the sake of this conversation, let's take one significant change that I feel is better over the way things are done in v1.

v2 deprecates all the Global* methods of accessing global flags. Instead, it introduces the concept of the parent context. The flags now traverse through the Lineage and try to find out the flags they can access through the parent command or global app-level flags.

I think this is a good feature to have. It's more elegant. At the same time, it would break the API with v1.

If we really want to have one single source of truth of the library code in the master branch, I think we must agree to give up on v1 at some point. With the non-compatible changes in place in master, it would get difficult even to have a bug fix or a backported feature for v1 once the merge is done.

The way I see it, this is how we can do it. Fork out a branch from master at tag v1.22.1 called v1 which can be used for maintenance, backporting new features, and bug fixes. We would obviously EOL it and specify a date when it will stop receiving such fixes and urge people to move to v2. The migration is not very difficult and people who chose to do it will get on board v2 and others can safely continue to use v1.x.x.

Now, the master only has v2 code which we can continue to work on.

[lynncyrin]

Fork out a branch from master at tag v1.22.1 called v1 which can be used for maintenance, backporting new features, and bug fixes. We would obviously EOL it and specify a date when it will stop receiving such fixes and urge people to move to v2. The migration is not very difficult and people who chose to do it will get on board v2 and others can safely continue to use v1.x.x.

I would like to propose a slightly more aggressive version of this plan, with some more detail!

As soon as https://github.com/urfave/cli/pull/892 is ready to land into master, we take the current master version and release it as 1.23.0. We'll also take the current documentation and changelog and maintain v1 and v2 versions. From that point on, we no longer release features for v1, but we do release bug fixes - particularly bug fixes for regressions.

We can also slightly modify the release pattern specifically for v1. Once v2 hits master, and the bug fix PRs for v1 should also update the changelog and be released immediately after being merged into the v1 branch. This will make PRs to v1 more work, but will ultimately serve to reduce maintenance burden. PRs to v2 can continue being made the same way they are currently.

We continue in this state for exactly 1 year from the date of v2 being merged into master. After that year, we no longer accept any PRs to v1. I can be responsible for creating all of the PRs / documentation about this - in particular I want to create pull request and issue templates that explain to people how this all would work.

[lynncyrin]

There's portions of the above suggestion that I feel pretty good about, since I imagine they won't be controversial 🙂 I'm going to stand up PRs for them now.

[AudriusButkevicius]

Sorry, have not red comments in full, but I vote for "once we merge v2, v1 is dead, and we only merge bug fix PR's (yet do not promise to fix stuff, people experiencing the bug can do that (unless its something tragic)).

[lynncyrin]

Looking at the current state of the V2 PR https://github.com/urfave/cli/pull/892/, here's my summary of the changes:

• all flags are global now
• flag getnames to changed names
• flgs can now return errors
• flag Aliases attribute added, flag Name now only contains a single name
• many attributes changed to pointers for performance reasons
• new flags added (floag 64 slice flag, path flag)
• bool t flag removed
• envvar string changed to envvars string[]
• ??? miscellaneous changes to command categories
• Action interface{} changed to Action ActionFunc

This is me reporting on the state of that PR, not making any judgements about why changes were made / encouraging them to be shipped.

[lynncyrin]

??? miscellaneous changes to command categories

☝️ I'll get some more clarity on this before we merge

[lynncyrin]

v1 historical branch is here => https://github.com/urfave/cli/tree/v1

I gave it similar branch protection as master, with the exception of making the number of required reviews for the v1 branch be 1 (which contrasts the 2 that master requires).

[lynncyrin]

👀 I just merged all of @asahasrabuddhe's great work on the v2 PR!!!!! 🎉🎉🎉 https://github.com/urfave/cli/pull/892

Since v2 has now landed, I'll do a sweep through our open issues to see anything should be up-prioritized.

I created this ticket for a fast-follow migration guide https://github.com/urfave/cli/issues/921

[lynncyrin]

I'm available at around 5 hours a day over the next ~9 days to do any fast follow IC work on potential v2 bugs, if we find any 👀 I'm going to try migrating one of my CLIs, see what I find.

[lynncyrin]

@marwan-at-work v2 is now in master! I know you've been waiting for that for a while 🙏

[marwan-at-work]

@lynncyrin that's awesome, great work 💯💯💯 👏

[lynncyrin]

I'm going to release the current master version as 2.0.0 today ✅

[asahasrabuddhe]

So excited for this to happen!

[lynncyrin]

Here's the ✨Official Git Tag ✨for v2 => https://github.com/urfave/cli/tree/v2.0.0

It's now available via go get ... @v2.0.0

[lynncyrin]

2.0 is looking pretty stable now, so I'ma close this ♻️