search

ponylang / pony-tutorial

:horse: Tutorial for the Pony programming language
http://tutorial.ponylang.io
BSD 2-Clause "Simplified" License
310 stars 111 forks source link

Advertise Markdown files in docs/ as "source" files #520

Closed i-ky closed 11 months ago

i-ky commented 1 year ago

Right now GitHub does not detect the language of this repo: image

After the fix it will identify Markdown as the main language: image image

In my opinion, this will help people (e.g. documentation writers and beginner programmers) to find a project to contribute to.

SeanTAllen commented 1 year ago

We are unsure about doing this. @i-ky we can see on other repositories that this is done for at least non markdown languages. Do you know why the markdown isn't recognized here? If we were to accept this, we'd want to do it across various repositories that are "markdown driven".

i-ky commented 1 year ago

@SeanTAllen, thank you for the feedback!

Do you know why the markdown isn't recognized here?

Markdown is recognized, but Markdown is considered prose language (i.e. not source code). Also paths like docs/ and Readme.md are discarded as documentation by default. (See how linguist works.) I believe this is a heuristic based on the fact that many projects store documentation alongside source code in the same repo. We don't want to "dilute" or even overpower language stats with Markdown, TeX, HTML and other common documentation formats. Unfortunately, for projects that have separate documentation-only repos this heuristic does more damage than good.

If we were to accept this, we'd want to do it across various repositories that are "markdown driven".

Feel free to point me to other repos, I will be happy to help fine-tune language detection there as well.

I've already made similar PRs to other repos:

SeanTAllen commented 1 year ago

@i-ky that makes sense. we'll discuss further next Tuesday at our sync meeting, if not sooner. Also relevant repos would be pony-patterns and ponylang-website. Also perhaps contributors.

i-ky commented 12 months ago

Also relevant repos would be pony-patterns and ponylang-website. Also perhaps contributors.

Filed PRs for pony-patterns, ponylang-website, contributors and rfcs:

  1. https://github.com/ponylang/pony-patterns/pull/69
  2. https://github.com/ponylang/ponylang-website/pull/886
  3. https://github.com/ponylang/contributors/pull/24
  4. https://github.com/ponylang/rfcs/pull/212

I deliberately commit changes to default branches of my forks for you to see the effect on GitHub's language detection.

Also https://github.com/ponylang/sublime-pony does not have any source files detected. My experience with Sublime Text is very limited, so I am not sure which would be the best way forward. Maybe we can add a few gitattributes to tune language detection manually, maybe we can submit a feature request to linguist for better support of Sublime Text plugin repos.

Additionally .ctags file should probably be marked as "source" of https://github.com/ponylang/pony-ctags, but linguist does not seem to have support for such format.