Hermes Guide: versioning

[adizere]

Summary

The guide we keep at hermes.informal.systems is pretty amazing.

For easier maintenance, some ideas for future work include:

• [x] modify the ci action to unpin from the dev branch (#610)

https://github.com/informalsystems/ibc-rs/blob/5dc062707b2f5f34722e203f26b74658646b76c0/.github/workflows/guide.yml#L3-L6

• [ ] include a versioning scheme, so we can access a specific version of the guide, for example

hermes.informal.systems/v1/ hermes.informal.systems/v2/

Note that the current versioning scheme is very crude and it's just a remark in the guide readme file.

• [ ] design a staging area, so that we're keeping multiple instances of the guide online: one that reflects whatever is in the master (e.g., via uri hermes.informal.systems/master/), and the other versions for all published (tagged) versions. It would be amazing if we can automate the tagging process to deploy new versions out of master.

• [ ] run the guide build job against two chains, and use something like termbook to automatically insert the results of the various commands instead of having to maintain those manually.

---

For Admin Use

• [X] Not duplicate issue
• [X] Appropriate labels applied
• [X] Appropriate milestone (priority) applied
• [X] Appropriate contributors tagged
• [X] Contributor assigned/self-assigned

[romac]

modify the ci action to unpin from the dev branch

https://github.com/informalsystems/ibc-rs/pull/610

[andynog]

Did some preliminary investigation on how to support versioning with mdbook. There might be a few options.

Is the idea to have some sort of a drop down box on the documentation site so users can switch between versions (something similar to cargo docs site) ?

[romac]

That would be nice feature to have but it's not mandatory imho.

On 4 Feb 2021, at 22:32, Andy Nogueira [email protected] wrote:

Did some preliminary investigation on how to support versioning with mdbook. There might be a few options.

Is the idea to have some sort of a drop down box on the documentation site so users can switch between versions (something similar to cargo docs site) ?

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/informalsystems/ibc-rs/issues/609#issuecomment-773617324, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAA2CYK5LUXRDO4NMNH2YEDS5MHAXANCNFSM4XDFMZWA.

[andynog]

I think supporting that will be too complex at the moment with mdBook, probably would need to create a pre-processor or add-in to support that. The easiest way is to have maybe separate jobs in CI (like one to publish the guide when master is changed and push to gh-pages branch) and other that pushes the staging to another place so we can test the updates to documentation on a different place.

[adizere]

Beside versioning, I found this principled approach to doing documentation: https://documentation.divio.com. Would be good if we try to apply some of the ideas in there, in particular these dimensions