Fix the order in which README files are chosen

[karthik]

Hi @bkeepers
Following the merge of PR #343, everything has been working great, but there is a new issue that has come up. If a repository contains both a README.Rmd and a README.md, GitHub now shows README.Rmd. I'm sure you have some mechanism in place to handle which file to choose when repos contain multiple README files/formats.

Example: https://github.com/ropensci/git2r
Here you see the raw, unparsed Rmd is shown by default, when in fact the parsed README is what needs to be displayed.

So if I were to have README.md, README.rst and README.txt (same repo and same folder), how is the order determined?

If it is possible to set the order, README.md should always be displayed over README.Rmd since the latter contains unparsed code. The purpose of having both files in the same folder is so that with each software update, the author can parse the Rmd file and have the most up to date code rendered into the README.md.

I apologize if this issue needs to go elsewhere so please close and open in the right repo.

Thank you.

[renkun-ken]

Fully agree with @karthik! I would appreciate it if the the display order is set like:

If final result (README.md) exists, show it;
otherwise, show its producer (README.Rmd).

[hilaryparker]

Yes, +1 to this! I'm VERY happy with the .Rmd rendering. However, this change has broken my workflow because I use README.Rmd -> README.md as my default way for creating reports.

[bkeepers]

Interesting. Currently we just choose the first README that can be rendered, where "first" is determined by the order of the git tree. I don't know if git trees are in any deterministic order.

I'll work on getting this fixed on Monday.

I apologize if this issue needs to go elsewhere so please close and open in the right repo.

You'll generally get a faster response if you contact [email protected].

[jennybc]

👍 to displaying README.md by default, even if a (now beautifully rendered!) README.Rmd is also present

[leeper]

+1

[leeper]

This issue is solved by changing the .Rmd extension to .rmd. Example: https://github.com/rOpenGov/recalls

[bkeepers]

This issue is solved by changing the .Rmd extension to .rmd. Example: https://github.com/rOpenGov/recalls

This is true. It looks like git trees use asciibetical order, so .md comes after .Rmd and before .rmd.

Either way, we don't expect everyone to rename their files, so we will get it fixed.

[ymendel]

Your README.md files should now take precedence over the README.Rmd files.

To answer the question in the original post, generally we look for "formatted" README files before plaintext ones, and we sort them alphabetically (now — it was ASCIIbetical until just a short while ago, hence the problem with .Rmd files). That means, for the specific example, the order is

1. README.md
2. README.rst
3. README.txt

(In all examples, the first element in the list is the one used as the README.)

But that's a little unclear because it's also just plain alphabetic order. If instead of ReStructured Text there were a format called "ZappoText" with an extension .zt, then we'd have

1. README.md
2. README.zt
3. README.txt

And if the markdown file were deleted, it'd be

1. README.zt
2. README.txt

And finally, if the only existing file were the plaintext README.txt, that would be the one used.

That's what we do right now, at least. We may do something more sophisticated in the future. We may never find something that works better than this, which is good news for the AsciiDoc fans.

[hilaryparker]

Thank you!