I recently became colleagues with @jfmengels, and I decided to try out his elm-review tool. I find the repo on GitHub, 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, 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.
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.
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.
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.
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)
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 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.
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
You could submit a PR to 
And cool to add this to elm-review!
