Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

UseShortOptionHandling not found in v1.21.0 #877

Closed
bygui86 opened this issue Aug 26, 2019 · 8 comments
Closed

UseShortOptionHandling not found in v1.21.0 #877

bygui86 opened this issue Aug 26, 2019 · 8 comments

Comments

@bygui86
Copy link

bygui86 commented Aug 26, 2019

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

@coilysiren
Copy link
Member

The PR for that was merged 21 days ago #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 #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
Copy link
Member

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

@asahasrabuddhe asahasrabuddhe reopened this Sep 7, 2019
@coilysiren
Copy link
Member

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.

@coilysiren
Copy link
Member

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
Copy link
Member

rliebz commented Sep 9, 2019

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
Copy link
Member

rliebz commented Sep 9, 2019

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.

@coilysiren
Copy link
Member

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!

@coilysiren
Copy link
Member

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

4 participants