godotengine / godotengine/godot-docs

Intuitive 3.x to 4.0 transition (after 4.0 leaves beta)

Open
#6,260 1 comment 2 reactions 0 assignees View on GitHub
content:website enhancement
Dominant language
reStructuredText
Stars
5.7k
Forks
3.8k
Avg merge
1d 20h
Merged PRs (30d)
25

Description

This idea was inspired by this https://github.com/godotengine/godot-docs/issues/6259

Basically, in 4.0 assume you type some 3.x code and you get a compiler error. Obviously, it is not the compiler's job to tell you what it has been converted to. 3-to-4 project converter exists which is great. But for documentation and tutorial code, this is not good, as there is currently no page for a list of all changes (mostly code) from 3.x to 4.0 https://github.com/godotengine/godot-docs/issues/4960

Even if that page exists, it is the suggestion in this very issue which ensures no1 "gets left behind" (obviously 4.0 must leave beta first lol)

First of all, an auto-generation script in the docs, where via pull requests, users can manually set redirection, when you change in the URL, the `/stable/` into `/latest`
An example:
[3.x] https://docs.godotengine.org/en/stable/classes/class_poolvector2array.html?highlight=poolvector2array
[4.x] https://docs.godotengine.org/en/latest/classes/class_poolvector2array.html?highlight=poolvector2array

The above gives page not found, but if some user had put redirection, it should redirect here https://docs.godotengine.org/en/latest/classes/class_packedvector2array.html?highlight=packedvector2array

The problem with this suggestion is that very very few users will think to touch/edit/tweak the `/stable/` URL to `/latest`, and would rather search engine or search github issues or whatever megadocument contains all changes.

So, the best suggestion is this

----------------------------------------

A script which checks if a 3.x page exists in 4.x (so if `/stable/` exists in `/latest/`) and adds them to a .txt to be posted here (pin that .txt plz)
Then, users can manually set URL redirects for the "replacement" or renames, and add them to this .txt

With that .txt, use another script to go through all the pages in the .txt and add at the bottom a "Migrated to Y" block (e.g. note block or warning block), so users familiar to 3.x and comfy with their `/stable/` docs, have no trouble finding replacements. Basically, this should be the final update to the 3.x docs.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.