search

TuringLang / docs

Documentation and tutorials for the Turing language
https://turinglang.org/docs/tutorials/docs-00-getting-started/
MIT License
225 stars 97 forks source link

Versioning of website based on Turing's versions #478

Closed shravanngoswamii closed 18 hours ago

shravanngoswamii commented 3 weeks ago

Now we have to make some changes in Turing.jl's workflow for triggering this workflow on new releases! Its not necessary because this will automatically update it when new commit will be made in this repo after version changes!

github-actions[bot] commented 3 weeks ago

Preview the changes: https://turinglang.org/docs/pr-previews/478, Please avoid using the search feature and navigation bar in PR previews!

shravanngoswamii commented 2 weeks ago

Update: Changelog and Versions will be added to sidebar of docs and tutorials https://github.com/TuringLang/turinglang.github.io/pull/74 — this will be closed with it!

shravanngoswamii commented 2 weeks ago

For the listing, only minor versions will be there now! In our gh-pages, should we have only minor versions or all? If all, then this PR is good to go!

shravanngoswamii commented 2 weeks ago

Should we have Changelog inside versions dropdown? Currently, it's like this: Screenshot 2024-06-14 092957

yebai commented 2 weeks ago

Thanks @shravanngoswamii. Let's create a qmd file for versions, too, and link to it from the left menu, instead of maintaining a list in the quarto config file.

For the listing, only minor versions will be there now! In our gh-pages, should we have only minor versions or all? If all, then this PR is good to go!

We only list minor versions, but they should point to the most recent bugfix release, e.g. v0.33 should always point to v0.33.most_recent_release.

shravanngoswamii commented 2 weeks ago

Ok, got it! I will update it soon!

shravanngoswamii commented 2 weeks ago

link to it from the left menu, instead of maintaining a list in the quarto config file.

Updated the script!

We only list minor versions, but they should point to the most recent bugfix release, e.g. v0.33 should always point to v0.33.most_recent_release.

In latest version: latest bug fix version will appear In Stable version: latest minor version will appear In Previous Versions: all versions excluding latest, stable and those which have docs in our old site! In Archived Versions: all our versions that are in our old website.

I need some suggestions:

  1. Latest version also have link to Changelog, so should we keep Change log link in left sidebar or not?
  2. Should we have a version's dropdown in nav bar or not (I think it's not necessary requirement!)

Have a look at versions file now: https://turinglang.org/docs/pr-previews/478/versions.html

shravanngoswamii commented 2 weeks ago

I was adding the deprecation note in our old docs but I am having some issues understanding that site! Each html file in our old docs have links to css file like these /v0.31/some/folder, even if site is of version v0.28.2 then also html files in that version have link like v0.28/some/file and these folders(v0.28, v0.31) do not even exist so how is the site getting styles?

update: I searched a bit and found out that its using symbolic links!

shravanngoswamii commented 2 weeks ago

please also review the deprecation note in this: https://turing.shravangoswami.com/ui/v0.31.1/

yebai commented 1 week ago

Thanks @shravanngoswamii -- it looks nice.

Latest version also have link to Changelog, so should we keep Change log link in left sidebar or not?

Let's remove the link to change the log elsewhere except the one in versions.qmd.

Should we have a version's dropdown in nav bar or not (I think it's not necessary requirement!)

That would be nice if possible.

shravanngoswamii commented 1 week ago

I am testing this in various cases, I will let you know when I am done!

shravanngoswamii commented 1 week ago

@yebai I tried many things for suggesting the changes to VERSION if it contains old version but no one is working as expected, or maybe I used them in wrong way! I tried https://github.com/parkerbxyz/suggest-changes and https://github.com/reviewdog/action-suggester, but both are not working the way I want them too! So I used normal comments!

Currently, we have these: publish.yml: check the VERSION file, push site to versioned and root folder vcheck.yml: check that the VERSION file have the latest version or not, if not then it comments in PR to update it to latest

shravanngoswamii commented 4 days ago

I tried almost everything that I could, and I was not able to figure out what was the issue! Then suddenly I saw the issues of this workflow and found out that it does not support diffs that change single line, we can use it after this PR is merged!

shravanngoswamii commented 1 day ago

@yebai This PR is good to go, that suggest changes workflow PR is merged — https://github.com/parkerbxyz/suggest-changes/pull/31, and it's working fine now! You can see the example here: https://github.com/shravanngoswamii/docs/pull/46

shravanngoswamii commented 1 day ago

Still I have one more question, when we update any previous release then docs will be pushed to that particular version along with the root folder. So should I put the if condition for pushing to root folder for latest version, I mean after these docs will only be pushed to root folder when VERSION is latest! But even if we do this, then what about the case where we need the changes of previous release in latest!

yebai commented 22 hours ago

Still I have one more question, when we update any previous release then docs will be pushed to that particular version along with the root folder. So should I put the if condition for pushing to root folder for latest version, I mean after these docs will only be pushed to root folder when VERSION is latest!

Let's do it.

But even if we do this, then what about the case where we need the changes of previous release in latest!

One should always refer to explicitly versioned docs for previous releases.

shravanngoswamii commented 22 hours ago

Let's do it.

Done!