Focusing the 3.0 release?

[epage]

I'm wondering if we can better focus the 3.0 release. Some considerations

• Does the bug already exist?
• Does the bug fix require a breaking change?
• What is the scope (size) of the remaining work?
• What is the severity of the bug?
• How many people are impacted?

[epage]

My candidates for deferral:

• Allow Enum Variants as Arg|ArgGroup|SubCommand keys #1104 (moving away from stringly-typed), see my comment for motivation
  • Also covers Add ability to derive ClapKey to use enum variants as keys #1663
• Dedupe Tests #1078 (dedupe tests): existing issue with minimal impact
• completions: Support adding additional code to complete values #568 (dynamic completions possible dupe of Dynamic completion support #1232): completely new feature that needs design and implementation work but shouldn't be breaking
• value_of_t() is difficult to use with optional arguments  #2505 (optional with value_of_t): has reasonable workaround
• Support automatic subcommands for completion #810 (automatic completion subcommands): new
  • This is one where I'm mixed. I agree with moving clap_complete out but that probably justifies smoothing out the path to using it some more

Some that sound deferrable but I'm unsure:

• Argument with default_values conflict when inside groups #1906
• requires_all ArgGroup with a default, causes the entire ArgGroup to be required #1586
• Differentiate between default_value and env in ArgMatches #1345
• specifying default value makes field required #2043

All of the above seem to be of a form of needing to keep track of authorship or maybe applying values in layers. The scope seems big while the value seems more niche.

[epage]

The ones you are unsure might need some breaking changes, so they are not deferrable.

Even with requiring a breaking change, are they important enough to block things now or should we put them in the 4.0 milestone?

, #2505 will be part of the breaking changes to improve the ArgMatches

Is there an issue or PR that talks about what these further breaking changes are to ArgMatches?

[pksunkara]

Even with requiring a breaking change, are they important enough to block things now or should we put them in the 4.0 milestone?

I would say so.

Is there an issue or PR that talks about what these further breaking changes are to ArgMatches?

No, it's just something I realized recently. Bunch of value_of_* and validation issues are related to each other and it looks like we need some breaking changes to fix this.

[epage]

No, it's just something I realized recently. Bunch of value_of_* and validation issues are related to each other and it looks like we need some breaking changes to fix this.

Could you share your thoughts on this? If I understand the direction you are interested in, I can help make it a reality. As I mentioned, my company has agreed that getting clap3 moving forward and released after all of these years is important enough to let me work on it full time.

[pksunkara]

I will create an issue consolidating my thoughts and linking all the relevant issues.

[pksunkara]

Further discussion in #2683

[djc]

I think the current direction of postponing clap 3 until all these issues are fixed is a bad idea. Yes, there may be some breaking changes accumulating that you'd like to fix in order to make the API better, but the problem is that any value from the current master branch is not shipping to users and that also means there could be a lot of regressions in there that are not being found because only a relatively small audience is testing beta releases or the Git branch. Here's an epic treatise on why this is a bad idea. I'm half-inclined at this point to just fork clap 3 to get it unstuck, because the current approach (with 38! issues in the 3.0 milestone) is no way to ship software.

[epage]

I completely understand. I was in your same boat, even considering forking clap.

I think things are different now but not all of it is visible yet, so let me explain.

First, some things slowing down clap3

• clap3 was started when the ecosystem was less mature and generally assumed a higher bar for breaking changes (which also led to the proliferation of the 0.x crates). This led to a lot of extra work being crammed into the release at various levels of polish
• Through all of that time, we've had a lot of one off contributions of additional features (help heading, replace, etc) that add to the remaining polish / docs work
• Life took over for the original author and maintainers have had various levels of time for both writing and reviewing code (e.g. I've had PRs go over a month without a word from maintainers)
• We all have our little pet features we want to see slip in :)

Why things are different

• My work is sponsoring my Rust development and we've agreed that clap3 is my top priority
• I've been made a maintainer, with permission to merge my own code if other maintainers aren't able to get around to it
• We've evolved with the community and are more open to breaking changes in the future, reducing the pressure on this release
• We've formed a maintainer triumvirate, giving us an opportunity to question each other's pet projects to help pair things down and break ties
• On a maintainer zulip stream, we are continuing the conversation started in this discussion and are close to a decision on what will be cut. I started the zulip discussion from the position of justifying why something should be kept in the release rather than justifying why something should be deferred.

As an outcome, our velocity of merges has been climbing and soon our bar should be lowered.

With that said, I do not think we should release as-is. A fork or a random arg parsing crate can easily release as they wish. Due to the breadth of clap's users, I feel there is an expectation of quality for us to meet with any release (the cost of success). We shouldn't be a KDE 4.0 or Python 3.0 where users think it is a widespread release while in reality it is more of a half-baked preview. We shouldn't have major regressions (including compared to structopt since we've forked it) and the features should be ready enough.

[djc]

I'm happy to see the situation improving. I think a good outcome would be to make sure that the various way to discover remaining work for 3.0 are actively triaged and reduced to make it possible to (a) keep track of progress, (b) help out where necessary.

[epage]

Yes, we'll move work out of the 3.0 milestone and I want to break down some of the nebulous items (like the tracking issues) into individual issues so there is a clear target.

[pksunkara]

I think a good outcome would be to make sure that the various way to discover remaining work for 3.0 are actively triaged and reduced to make it possible to (a) keep track of progress, (b) help out where necessary.

I am not sure I understand what you are asking for. Wasn't the 3.0 milestone a good tracker for discovering what's left? Github also shows us on the issue if it has been removed from a milestone. I have done this audit of moving work out quite a number of times over the past two years.

[djc]

The milestones kind of suck because they make it hard to see, at a glance, if/how much progress is being made. It also does not give me confidence that there are 36 issues there including some labels "nice to have" or "want to have". IMO the window for getting those kinds of things in has long since passed, and it's time to focus only on things that affect backwards compatibility.