Giters

aantron / dream

Tidy, feature-complete Web framework

Home Page:https://aantron.github.io/dream/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Example links should point to correct version

yawaramin opened this issue · comments

commented

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

commented

Agreed in principle. There are a few difficulties with maintaining synchronization between the examples and the latest release:

  1. I tend to develop the examples together with master.
  2. It takes some effort to maintain the right link to the latest release. Maybe we can use a moving ref for this purpose.
commented

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!
commented

I think the best solution is to just get back to a regular release schedule, so that the amount of time the examples are out of sync with master the latest release is minimized. I've proposed a release to opam-repository.