Prefer the README file that has the basename README

[mojavelinux]

I'm facing a situation where the translated version of the README (e.g., README-jp.adoc) in a gem is being selected over the primary (English) one (README.adoc). (See https://www.rubydoc.info/gems/asciidoctor/2.0.0). This happens because of how the the README files are globbed.

The README files in the gem are as follows:

README.adoc
README-de.adoc
README-fr.adoc
README-jp.adoc
README-zh_CN.adoc

The glob used by YARD is README*. For some reason, that results in README-jp.adoc being selected as the default. (It appears the result of the glob isn't sorted at all).

I think the file with the basename README (e.g., README.adoc) should be preferred over files that are hyphenated. I think most people would agree that this is the master README file in all situations.

(I'm aware I can include a .yardopts file to select a specific README. However, I can't make that change for gems that have already been released).

[lsegal]

For some reason, that results in README-jp.adoc being selected as the default. (It appears the result of the glob isn't sorted at all).

I believe that the list is sorted lexically, which would make sense if README-X was chosen over README.X since:

> '-'.ord < '.'.ord
=> true
> ['.', '-'].sort
=> ["-", "."]

That said, I believe globs are system dependent, so the behavior certainly isn't guaranteed. This can be problematic in cases where you're trying to deliver consistent docs across platforms.

I think a PR to prioritize README followed by README.* could be acceptable, but note that such a PR only solves this specific case. Users who name files as README.de.adoc would have the same problem you initially have here (this is a file naming convention the Ruby repo seems to use).

Sorting the entire list could be done but could be seen as a breaking change, since it would change the behavior for systems that don't sort globs initially. I'm not sure how I feel about that, given that it (a) changes behavior but (b) is undefined behavior.

Another heuristic we could use would be to stable-sort by the frequency of '.' in the strings. That should ensure README < README.{adoc,md,txt,...} < README.{en,de,fr,...}.{adoc,md,txt,...}. You would probably need to couple it with the specific README,README.* priority rule to also solve for your case, though.

[mojavelinux]

I think a PR to prioritize README followed by README.* could be acceptable

I'd be glad to.

but note that such a PR only solves this specific case.

Well, it's the most likely scenario. Any project that has a single file extension README.* probably, if not always, wants that to be used over any README-*. It's extremely clear what the single file extension README.* represents. It also happens to be the same logic GitHub uses. That's why the English README is shown at https://github.com/asciidoctor/asciidoctor and not the Japanese one (or any other transation).

Users who name files as README.de.adoc would have the same problem you initially have here

That's why I say "single file extension". That's important.

I believe globs are system dependent, so the behavior certainly isn't guaranteed.

No question, at the very least making it deterministic would be a good step forward.

Sorting the entire list could be done but could be seen as a breaking change, since it would change the behavior for systems that don't sort globs initially.

If we fix the main issue at hand, I don't think the sorting becomes all that important. Though it would still be good to stabilize it.

[mojavelinux]

that results in README-jp.adoc being selected as the default

Apologies, I was mistaken. It selects the Chinese translation (zh_CN), which makes sense because it's at the end of the list. That must mean it's reversing the list at some point. I'll try to figure out what the existing rules are and report back.

[mojavelinux]

Here's the order that Dir.glob returns (Ruby 2.6):

README-zh_CN.adoc
README.adoc
README-fr.adoc
README-jp.adoc
README-de.adoc

go figure

[mojavelinux]

See PR #1233.