search

leostera / caramel

:candy: a functional language for building type-safe, scalable, and maintainable applications
https://caramel.run
Apache License 2.0
1.06k stars 25 forks source link

Build documentation on CI instead of requiring contributors to run mdbook locally #47

Closed michallepicki closed 3 years ago

michallepicki commented 3 years ago

I would like to contribute to the documentation, but I am not very happy when doing that requires me to install additional tooling. Then, there are potential conflicts in HTML. Additionally, I think because mdbook is available in various versions and platforms, requiring contributors to install it may result hard to debug bugs or regressions.

Rendering the documentation on CI, would allow contributors to only modify .md files to update the documentation. Rendering could be done in a workflow that only runs from master, checks out the changes, runs mdbook and pushes rendered HTML to a separate branch. (There is a small security concern here, to not allow people to push to that branch from CI runs e.g. on pull requests). I saw similar solutions using something-different-than-jekyll to use GitHub Pages for a blog. (I am assuming here that the manual is served from Github Pages, but if it's not, then deployment would probably be similar to the current one, just based on a different branch.)

michallepicki commented 3 years ago

I could probably work on that sometime this week (if approved)

michallepicki commented 3 years ago

Here are permissions for the GITHUB_TOKEN that is automatically available in each action. The forked repos already have only a read permission. For PRs from within the repository (created by maintainers) I think configuring the action to only run from master is good enough.