jfmengels / elm-review-documentation

Provides elm-review rules to help with the quality and correctness of your Elm project's documentation
https://package.elm-lang.org/packages/jfmengels/elm-review-documentation/latest/
BSD 3-Clause "New" or "Revised" License
6 stars 2 forks source link

New rule: No pointing to resources on master #7

Closed jfmengels closed 3 years ago

jfmengels commented 4 years ago

What the rule should do:

Forbid links to resources on the master branch, for resources hosted on GitHub. These links should be reported in module documentation and in the README

What problems does it solve:

I often see READMEs containing an image stored on the master branch to something like https://raw.githubusercontent.com/jfmengels/elm-review/master/documentation/images/elm-review-report-hq.png

The problem with that is that if that images is ever changed/moved/removed on the master branch, then the image will disappear from the documentation. If instead, we made the link point to an image hosted in a Git tag or a SHA, then the image would stay there forever, like https://raw.githubusercontent.com/jfmengels/elm-review/2.0.1/documentation/images/elm-review-report-hq.png

I think we can apply this to other resources, like Markdown or any kind of files hosted on GitHub (through raw.githubusercontent.com or github.com (like https://github.com/jfmengels/elm-review/blob/master/documentation/images/elm-review-report-hq.png)

Example of things the rule would report:

{-|

![](https://raw.githubusercontent.com/jfmengels/elm-review/master/documentation/images/elm-review-report-hq.png)

-}

Example of things the rule would not report:

{-|

![](https://raw.githubusercontent.com/jfmengels/elm-review/2.0.1/documentation/images/elm-review-report-hq.png)

-}

When (not) to enable this rule:

I am looking for: