Example links should point to correct version
yawaramin opened this issue · 3 comments
On the Dream web page: https://aantron.github.io/dream/
All the example links seem to point at the master
branch, eg https://aantron.github.io/dream/#sql
Dream provides thin convenience functions over Caqti, an SQL interface with several back ends. See example h-sql
However these examples can change significantly between the last released Dream version and the master
branch. So they can fail to compile when the user tries them.
We should make sure all the links point to the tagged versions in the repo which correspond to the displayed latest opam release, eg: https://github.com/aantron/dream/tree/1.0.0-alpha5/example/h-sql
Agreed in principle. There are a few difficulties with maintaining synchronization between the examples and the latest release:
- I tend to develop the examples together with
master
. - It takes some effort to maintain the right link to the latest release. Maybe we can use a moving ref for this purpose.
Yeah even if we make the simplifying assumption that the library, docs, and home page are consistent with each other in each commit in master
, I guess it's still tricky to fix all the links in the web page. Maybe the postprocess script can read an environment variable to optionally get the 'commit-ish' (tag) that it should use and update all the GitHub links to use that.
Another simpler but more manual option might be to just add in each example's readme file, a link to the same file as of the latest Dream release. So eg for https://github.com/aantron/dream/blob/master/example/1-hello/README.md
# `1-hello`
View docs for version [1.0.0-alpha5](https://github.com/aantron/dream/blob/1.0.0-alpha5/example/1-hello/README.md)
<br>
This project is so simple that it doesn't even log requests!