search

libretime / website

Source for the LibreTime website
https://libretime.org
1 stars 2 forks source link

Change website versioning strategy #7

Closed jooola closed 1 year ago

jooola commented 2 years ago

We currently rely on docusaurus docs plugin for versioning. This brings a lot of complexity and duplicate files, specially now that I try to add multilingual documentation to the project.

In my opinion once a release is cut, we should not touch the versioned docs, or only for urgent bug fixes.

So I propose that we manage versioning using git. This would remove a copy from the repository. Here is what could be done:

I like how mkdocs does it, they build and push a version on the web server and never touch it again, meaning that the old versions are stored on the website and not in the version control system. So extending the above proposal, we might be able to accomplish the same by leaving old version on the webserver (Where would that be ? The gh-page branch might be ok, but only if we keep the branch as a single orphan commit, and not track each commits pushed to the branch).

paddatrapper commented 2 years ago

We would then have to host our own webserver?

jooola commented 2 years ago

No, I think we can use gh-pages, we need to work with subdirs and not flush everything when we push changes.

jooola commented 1 year ago

Maybe docusaurus versioning could work if we extract the website/docs to a new repo, but that's not the best way to enforce an up to date documentation.

paddatrapper commented 1 year ago

We could build it from this repo - maintain the unreleased docs here, then CI copies them over on every commit. Tags cause documentation related to that tag to be copied over to the docs repo. That way all dev happens here, but we don't need to maintain historical documentation in this repo

jooola commented 1 year ago

Just throwing ideas: Another crazy idea would be to try using sphinx, which can be a messy solution be works really great once nicely configured.

I've seen it using with a matrix of multiple versions and languages.

Though your solution is less extreme.

paddatrapper commented 1 year ago

I am hesitant to rewrite the docs and break links again....

jooola commented 1 year ago

@paddatrapper Could you create a website repo ? So we can experiment with this idea of pushing the docs to the website repo and keep the different versions over there ?

paddatrapper commented 1 year ago

https://github.com/libretime/website

jooola commented 1 year ago

Thanks

Le 16 décembre 2022 21:03:50 GMT+01:00, Kyle Robbertze @.***> a écrit :

https://github.com/libretime/website

-- Reply to this email directly or view it on GitHub: https://github.com/libretime/website/issues/7 You are receiving this because you authored the thread.

Message ID: @.***>

jooola commented 1 year ago

Transferring the issue to the website repo.