search

fayland / perl-Dist-Zilla-Plugin-GitHubREADME-Badge

Dist::Zilla - add badges to github README.md
Other
6 stars 9 forks source link

ReadmeAnyFromPod disagrees on markdown file extension #1

Closed schwern closed 7 years ago

schwern commented 10 years ago

CC @DarwinAwardWinner

Dist::Zilla::Plugin::ReadmeAnyFromPod writes a markdown type README as README.mkdn. This module looks for README.md. Github defaults to README.md.

I worked around this by giving an explicit filename to ReadmeAnyFromPod.

I propose y'all work out this gotcha. Perhaps one of...

  1. Change the markdown default in ReadmeAnyFromPod.
  2. Have GithubREADME::Badge look for README.md and then README.mkdn.
  3. Document the work around in GithubREADME::Badge and ReadmeAnyFromPod.

I'm a fan of 1, because Github is going to be driving a lot of markdown README use, and 2, because there's going to be pre-existing README.mkdn from existing users of ReadmeAnyFromPod. I'm not a fan of 3 because I'd rather see a problem fixed than have the user need a work around.

DarwinAwardWinner commented 10 years ago

The default markdown filename of ReadmeAnyFromPod is inherited from its ancestor ReadmeMarkdownFromPod, which has always used README.mkdn:

http://search.cpan.org/~jhelwig/Dist-Zilla-Plugin-ReadmeMarkdownFromPod-0.100700/lib/Dist/Zilla/Plugin/ReadmeMarkdownFromPod.pm (note this is a link to the original version before it was merged into ReadmeAny)

It's probably not a good idea to change the default now. If there's a lot of demand, I suppose I could add an "md" readme type that is simply markdown with a ".md" default filename. In any case, I haven't really seen a consensus on what the preferred extension is for markdown files, with .md and .mkdn being roughly equally common as far as I can tell. But if such a consensus does exist for perl or dzil, I'd be happy to follow it in ReadmeAnyFromPod.

schwern commented 10 years ago

What about a "github" type?

DarwinAwardWinner commented 10 years ago

Does Github itself actually prefer README.md and discourage README.mkdn? I wouldn't want to add a "github" type defaulting to .md unless that was somehow a github policy (that's why I suggested the neutral type "md" for it). As far as I can tell, it's only Dist-Zilla-Plugin-GitHubREADME-Badge that's hardcoded to use README.md. Maybe the filename should be an option and the default should be to check several common markdown-associated extensions (.md, .mkdn, .markdown) and pick the first one that exists.

fayland commented 10 years ago

Hi guys. I have made a new release with .mkdn, .markdown lookup. can you take a test and let me know if it works?

Thanks

schwern commented 10 years ago

@DarwinAwardWinner .md and .mkdn are both parsed by Github as Markdown. README.md is what Github creates for you when you initialize a repository.

So long as your two modules work together out of the box.

fayland commented 10 years ago

I'm using Milla with GitHubREADME-Badge and it works fine. I'd suggest you try that also.

Thanks