Cli: UseShortOptionHandling not found in v1.21.0

[bygui86]

Hi guys,

First of all great job! It's an amazing framework!

I'm relatively new to Go and most of all to Go Modules, so I'm almost sure that I'm doing something wrong.
But I found something weird in the flag App.UseShortOptionHandling.
In my example to understand the framework, I copied/pasted your sample about Combining short options in this file but for some reason the compiler complains about

$ go run examples/combine-short-opts.go
# command-line-arguments
examples/combine-short-opts.go:13:5: app.UseShortOptionHandling undefined (type *cli.App has no field or method UseShortOptionHandling)

What do I miss? What do I wrong?

Thanks for your help

[lynncyrin]

The PR for that was merged 21 days ago https://github.com/urfave/cli/pull/735, whereas 1.21.0 was released 25 days ago https://github.com/urfave/cli/releases/tag/v1.21.0. So this feature will be in release 1.22.0, which I'm tracking here https://github.com/urfave/cli/issues/867.

IME more mature projects solve this problem have having docs links that are specific to the version, like this page for example https://bundler.io/v1.15/man/bundle-config.1.html which is for bundler 1.15 - and then you can see that it's changed by version 2.0 https://bundler.io/v2.0/man/bundle-config.1.html. I'll put some thought into implementing something like that 🤔

[asahasrabuddhe]

I see there is a big discrepancy here.

I checked the tree of the 1.21.0 release. There is no UseShortOptionHandling option defined although the README.md encourages us to do so.

Please check:

https://github.com/urfave/cli/blob/e6cf83ec39f6e1158ced1927d4ed14578fda8edb/README.md#combining-short-bool-options

and

https://github.com/urfave/cli/blob/e6cf83ec39f6e1158ced1927d4ed14578fda8edb/app.go

[lynncyrin]

Ah, my comment may not have been clear enough! 1.21.0 does not contain UseShortOptionHandling because UseShortOptionHandling was merged after 1.21.0 was released. I'll gladly lift my hold on the 1.22.0 release so that we can release UseShortOptionHandling, since this is becoming confusing for >= 2 people.

[lynncyrin]

In the future we can implement a policy of only updating the readme as a part of new version releases, or something similar. This problem will continue coming up unless something changes about the way versions are released 🙁

[rliebz]

There is actually support for UseShortOptionHandling in 1.21.0, but it's only supported at the Command level, rather than at the App level. The feature introduced in #735 extends that support to the top-level App, which I figured was probably the more common use case, so the current docs were re-written at that time to emphasize the App config over the Command config.

The README for 1.21.0 references the UseShortOptionHandling flag for Command, which is just the part that was actually available at that time. The README there don't do a great job of making it clear how to use it, but it's at least accurate.

[rliebz]

This problem will continue coming up unless something changes about the way versions are released

I agree that this is important, and probably the real core of the issue here.

I'm not a huge fan of avoiding updating the README until release because it means that the people with the best understanding of the feature (i.e., the feature authors) would no longer be the people responsible for the documentation. Between that, and the fact that all the docs would have to be written at all once, potentially long after the feature was merged, the quality of docs might be taking a hit.

One relatively popular alternative is using static documentation generators such as mkdocs, docsify, or docusaurus, among others, to build a GitHub Pages site from a docs folder, which can be linked to in the README. The published version is always the latest tagged version, and every version is still available alongside the source code. The overhead is pretty small, and it's a one-time upfront cost that can be automated in CI rather than a change in process.

[lynncyrin]

One relatively popular alternative is using static documentation generators [where] the published version is always the latest tagged version

^ this is the solution I would prefer!

[lynncyrin]

I propose: we close this issue, and create another issue about setting up a "versioned documentation" system (described above)