# Problems with READMEs in Elm packages

**URL:** <https://discourse.elm-lang.org/t/problems-with-readmes-in-elm-packages/5396>\
**Category:** Request Feedback\
**Created:** [March 31, 2020, 10:57am UTC](https://discourse.elm-lang.org/t/problems-with-readmes-in-elm-packages/5396 "2020-03-31T10:57:49Z")\
**Posts on this page:** 9\
**Page:** 1

<div class="post-metadata">

**Author:** ![KasMA1990](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.elm-lang.org/kasma1990/32/2115_2.png) [@KasMA1990](https://discourse.elm-lang.org/u/KasMA1990)\
**Post date:** [March 31, 2020, 10:57am UTC](https://discourse.elm-lang.org/t/problems-with-readmes-in-elm-packages/5396/1 "2020-03-31T10:57:49Z")

</div>

I recently became colleagues with @jfmengels, and I decided to try out his `elm-review` tool. I find [the repo on GitHub](https://github.com/jfmengels/elm-review), and I start going through the README. It includes a link to some code in the package, but unfortunately the link is broken, so I take a look at it. I don’t understand the Markdown syntax being used for it, so I end up creating an issue that the link is broken. It then turns out that the link works fine if I browse the README through [the package registry](https://package.elm-lang.org/), and the syntax is for the Elm documentation tooling to use.

What went wrong? Should I have gone to the package registry to search for `elm-review` to begin with? I very rarely use that site for anything other than reading core documentation, and I’m practically embedded in GitHub anyway, so I don’t even think about whether I should use a different page to search for a package. Additionally, I know `elm-review`, like many other parts of the Elm toolchain we rely on at work, has a CLI attached which is not published in the Elm registry, so I naturally expect that looking there will give me an incomplete overview.

Maybe the issue is that the package registry and GitHub both rely on the same README file? If there were two different READMEs (e.g. README and PACKAGE\_README), then the GitHub one could easily link to the package registry, where everything is displayed as intended.

---

<div class="post-metadata">

**Author:** ![mdgriffith](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.elm-lang.org/mdgriffith/32/61_2.png) [@mdgriffith](https://discourse.elm-lang.org/u/mdgriffith)\
**Post date:** [March 31, 2020, 1:07pm UTC](https://discourse.elm-lang.org/t/problems-with-readmes-in-elm-packages/5396/2 "2020-03-31T13:07:29Z")

</div>

Hello!

So, the link in question as I see it is this one(or ones like it):  
`Check out the [`Review.Rule`](./Review-Rule) module for more instructions.`

Likely it just needs to be changed to an absolute URL, e.g.  
`https://package.elm-lang.org/packages/jfmengels/elm-review/latest/Review-Rule`

So, no need for any tooling change or anything 😃 You could submit a PR to `elm-review` though!

Probably this is just something package publishers should watch out for.

---

<div class="post-metadata">

**Author:** ![jfmengels](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.elm-lang.org/jfmengels/32/3124_2.png) [@jfmengels](https://discourse.elm-lang.org/u/jfmengels)\
**Post date:** [March 31, 2020, 1:18pm UTC](https://discourse.elm-lang.org/t/problems-with-readmes-in-elm-packages/5396/3 "2020-03-31T13:18:56Z")

</div>

That’s a good solution 👍

I’ll probably write an `elm-review` rule warning against relative links to files from the README, to avoid entering in this pitfall again (I’m enabling this in the next version).

One thing I’m not sure of with this solution though, and I keep wondering about this every time I use a link to the package, is whether to link to `latest/` or to hardcode the current version number in the link and hope to not forget to change it later. I guess it could be replaced automatically using a simple tool.

What is the approach that you usually use?

---

<div class="post-metadata">

**Author:** ![mdgriffith](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.elm-lang.org/mdgriffith/32/61_2.png) [@mdgriffith](https://discourse.elm-lang.org/u/mdgriffith)\
**Post date:** [March 31, 2020, 1:27pm UTC](https://discourse.elm-lang.org/t/problems-with-readmes-in-elm-packages/5396/4 "2020-03-31T13:27:06Z")

</div>

Good question! 🤔 And cool to add this to elm-review!

Barring having a perfect solution where all links are tested for the about-to-be-published version (which would probably be tricky to do), I think linking to `latest` is probably less error prone. Let’s say you release a patch release and change the documentation on the module that you’re linking to. Then people will go to the old version and not see your fantastic new documentation.

Side note, if you have the docs.json as a file elm-review can read, then you could do the about-to-be-published check. Ooo, maybe this is something Dillon’s Elm Publish Github Action could take care of, maybe in cahoots with elm-review.  
I’m thinking just a preflight check would be nice where it lists any links that are dead or referring to old versions as opposed to any auto-substitution.

---

<div class="post-metadata">

**Author:** ![jfmengels](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.elm-lang.org/jfmengels/32/3124_2.png) [@jfmengels](https://discourse.elm-lang.org/u/jfmengels)\
**Post date:** [March 31, 2020, 1:38pm UTC](https://discourse.elm-lang.org/t/problems-with-readmes-in-elm-packages/5396/5 "2020-03-31T13:38:06Z")

</div>

> Side note, if you have the docs.json as a file elm-review can read, then you could do the about-to-be-published check.

I’m adding support to read the `elm.json` file, the dependencies’ `docs.json` and the `README.md`. I don’t support the project’s `docs.json` though. If you think of nice use-cases for it, I’d love to hear about them (here or on Slack).

> I’m thinking just a preflight check would be nice where it lists any links that are dead or referring to old versions as opposed to any auto-substitution.

Reporting links to non-existing or non-exposed modules (or even to invalid functions/section ids) would be possible, and on my personal todo list 😃

Since I’m enabling access to the `elm.json`, we have the version and the name of the project, so we could detect links to out of date documentation too.

---

<div class="post-metadata">

**Author:** ![ianmackenzie](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.elm-lang.org/ianmackenzie/32/86_2.png) [@ianmackenzie](https://discourse.elm-lang.org/u/ianmackenzie)\
**Post date:** [April 3, 2020, 3:42pm UTC](https://discourse.elm-lang.org/t/problems-with-readmes-in-elm-packages/5396/6 "2020-04-03T15:42:37Z")

</div>

TL;DR: using `/latest` in READMEs is less error prone, doesn’t seem to cause major problems and lets me use a pretty simple and straightforward development workflow.

* * *

I’ve gone back and forth on this - for a while I tried to keep my package READMEs up to date with the current version number, but now I just use `/latest` everywhere since (as @mdgriffith mentioned) it seems less error-prone. And it also seemed that the errors that could arise from using `/latest` would be less problematic than if absolute version numbers weren’t updated correctly. Say someone is using an older version of a package and they click on a README link which takes them to the `/latest` version:

- they see some function that doesn’t exist in their current version
- they try to use it and the compiler gives them an error
- this (hopefully) prompts them to figure out what’s going on, they realize they’re on an old package version and they update - seems useful!

In contrast, if the package was updated but README links still linked to an older version, then someone using a newer version might get silently redirected to the docs for an older version, and not even realize that certain functions were available!

It’s also true that I always want the README on GitHub to always link to the latest version on the package site. If using absolute version links, this means that in the run-up to releasing a new package version, I’d either have to:

- only update the version numbers in the README _just_ before I publish the new release (so there’s no period where the README has been updated to link to a version that hasn’t actually been published yet)
- or be disciplined about always working in a separate `develop` branch or something, and only merge to `master` after each release (so that the README shown by default on GitHub always corresponds to the latest released version of the package, not the under-development version - but then this would mean that I couldn’t update it with, say, new contribution guidelines in between releases)

---

<div class="post-metadata">

**Author:** ![jfmengels](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.elm-lang.org/jfmengels/32/3124_2.png) [@jfmengels](https://discourse.elm-lang.org/u/jfmengels)\
**Post date:** [April 9, 2020, 3:21pm UTC](https://discourse.elm-lang.org/t/problems-with-readmes-in-elm-packages/5396/7 "2020-04-09T15:21:18Z")

</div>

Thank you for your insights @mdgriffith and @ianmackenzie 🙏

The solution I ended up is specifying the exact version, instead of `/latest`.

> If using absolute version links, this means that in the run-up to releasing a new package version, I’d either have to:
> 
> - only update the version numbers in the README _just_ before I publish the new release

and that’s what I will be doing, but automatically.

I built an [`elm-review`](https://package.elm-lang.org/packages/jfmengels/elm-review/latest/) rule which detects when the link uses `latest` or a different version than the current one. It automatically fixes the problem too, so even with a lot of links, it doesn’t become tedious.

The only downside is that I have to remember to at least run the tests between bumping the version and publishing the package, which is a risk I’m fine with. I don’t publish packages all that often at the moment, but I feel like I’m inclined to run tests twice rather than not running it at all.

I plan on releasing the rule in a bundle of package that will aim to help with managing the documentation in Elm packages/projects. In the meantime, if you’re interested you can copy the rule over [from here](https://github.com/jfmengels/review-documentation/blob/master/src/Documentation/ReadmeLinksPointToCurrentVersion.elm).

---

<div class="post-metadata">

**Author:** ![ianmackenzie](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.elm-lang.org/ianmackenzie/32/86_2.png) [@ianmackenzie](https://discourse.elm-lang.org/u/ianmackenzie)\
**Post date:** [April 10, 2020, 12:36am UTC](https://discourse.elm-lang.org/t/problems-with-readmes-in-elm-packages/5396/8 "2020-04-10T00:36:27Z")

</div>

That makes sense! I should have clarified that my comments were implicitly assuming that a tool like `elm-review` was not being used; I think the approach of letting `elm-review` keeping links up to date automatically makes a lot of sense. I’ll have to give it a try at some point 🙂

---

<div class="post-metadata">

**Author:** ![system](https://canada1.discourse-cdn.com/flex035/uploads/elm_lang/original/1X/50a05e53677a2c3b47776d7abd0f113eb50193a1.png) [@system](https://discourse.elm-lang.org/u/system)\
**Post date:** [April 20, 2020, 12:36am UTC](https://discourse.elm-lang.org/t/problems-with-readmes-in-elm-packages/5396/9 "2020-04-20T00:36:28Z")

</div>

This topic was automatically closed 10 days after the last reply. New replies are no longer allowed.