Rename Tutorials to Manual, move migration guide to a higher level (g…

…odotengine#6509)
Sightwalker · Jan 5, 2023 · 3f8fd6d · 3f8fd6d
1 parent b603b1d
commit 3f8fd6d
Show file tree

Hide file tree

Showing 6 changed files with 41 additions and 42 deletions.
diff --git a/_tools/redirects/redirects.csv b/_tools/redirects/redirects.csv
@@ -1,4 +1,5 @@
 source,destination
+/about/index.html,/index.html
 /classes/_classes.html,/classes/
 /community/tutorials/3d/mesh_generation_with_heightmap_and_shaders.html,/tutorials/3d/mesh_generation_with_heightmap_and_shaders.html
 /community/tutorials/gdnative/gdnative-c-example.html,/tutorials/plugins/gdnative/gdnative-c-example.html
@@ -277,6 +278,7 @@ source,destination
 /tutorials/debug/debugger_panel.html,/tutorials/scripting/debug/debugger_panel.html
 /tutorials/debug/index.html,/tutorials/scripting/debug/index.html
 /tutorials/debug/overview_of_debugging_tools.html,/tutorials/scripting/debug/overview_of_debugging_tools.html
+/tutorials/editor/upgrading_to_godot_4.html,/tutorials/migrating/upgrading_to_godot_4.html
 /tutorials/gui/bbcode_in_richtextlabel.html,/tutorials/ui/bbcode_in_richtextlabel.html
 /tutorials/gui/control_node_gallery.html,/tutorials/ui/control_node_gallery.html
 /tutorials/gui/custom_gui_controls.html,/tutorials/ui/custom_gui_controls.html

diff --git a/about/index.rst b/about/index.rst
diff --git a/index.rst b/index.rst
@@ -95,20 +95,24 @@ the top-level ``index.html`` in a web browser.
    getting_started/first_3d_game/index
 
 
-.. The sections below are sorted alphabetically. Please keep them that way.
+.. Sections below are split into two groups. First come meta sections, covering
+   general matters. Below that different areas of the engine are listed.
+   These sections are sorted alphabetically. Please keep them that way.
 .. toctree::
    :hidden:
    :maxdepth: 1
-   :caption: Tutorials
+   :caption: Manual
    :name: sec-tutorials
 
+   tutorials/best_practices/index
+   tutorials/editor/index
+   tutorials/migrating/index
+
    tutorials/2d/index
    tutorials/3d/index
    tutorials/animation/index
    tutorials/assets_pipeline/index
    tutorials/audio/index
-   tutorials/best_practices/index
-   tutorials/editor/index
    tutorials/export/index
    tutorials/i18n/index
    tutorials/inputs/index

diff --git a/tutorials/editor/index.rst b/tutorials/editor/index.rst
@@ -1,11 +1,11 @@
-Editor manual
-=============
+Editor introduction
+===================
 
 In this section, we cover the Godot editor in general, from its interface to
 using it with the command line.
 
-The editor's interface
-----------------------
+Editor's interface
+------------------
 
 The following pages explain how to use the various windows, workspaces, and
 docks that make up the Godot editor. We cover some specific editors' interface
@@ -35,12 +35,12 @@ should be aware of.
 
    using_the_web_editor
 
-For developers
---------------
+Advanced features
+-----------------
 
-The articles below focus on features for developers, like calling Godot from the
-command lines and using an external text editor such as Visual Studio Code or
-Emacs.
+The articles below focus on advanced features useful for experienced developers,
+such as calling Godot from the command line and using an external text editor
+like Visual Studio Code or Emacs.
 
 .. toctree::
    :maxdepth: 1
@@ -61,12 +61,3 @@ a project that's only 2D or only 3D and don't want to see what you don't need.
    :name: toc-editor-features
 
    managing_editor_features
-
-Upgrading to Godot 4
---------------------
-
-.. toctree::
-   :maxdepth: 1
-   :name: toc-editor-upgrading
-
-   upgrading_to_godot_4
diff --git a/tutorials/migrating/index.rst b/tutorials/migrating/index.rst
@@ -0,0 +1,20 @@
+Migrating to a new version
+==========================
+
+Godot :ref:`loosely follows <doc_release_policy>` a semantic versioning system,
+where compatibility is assumed between minor and patch releases, while major
+releases can break it. As such, it is generally not recommended to move projects
+between major versions during their development, especially if you've been
+working on them for a significant amount of time.
+
+Still, new features, usability improvements, or paradigm shifts in engine's
+internals may incentivize you to upgrade. Below is a list of articles that should
+assist you when upgrading your project between versions. Each article would try
+its best to document every important difference and provide you with a migration
+path.
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-migrating
+
+   upgrading_to_godot_4
diff --git a/tutorials/editor/upgrading_to_godot_4.rst → tutorials/migrating/upgrading_to_godot_4.rst b/tutorials/editor/upgrading_to_godot_4.rst → tutorials/migrating/upgrading_to_godot_4.rst
@@ -1,7 +1,7 @@
 .. _doc_upgrading_to_godot_4:
 
-Upgrading to Godot 4
-====================
+Upgrading from Godot 3 to Godot 4
+=================================
 
 Should I upgrade to Godot 4?
 ----------------------------