[WIP] Add documentation for the release cycle by AThousandShips · Pull Request #93 · godotengine/godot-contributing-docs

AThousandShips · 2026-07-01T14:08:14Z

Checklists for the release process

Still very much in progress but rough outlines for feedback and for the relevant teams to provide the steps for their areas

AThousandShips · 2026-07-01T14:10:14Z

@akien-mga Would appreciate some help on this section

Rough process dump for editor strings: https://gist.github.com/akien-mga/9357c5886e06fdff70f0499970cd4115

I'll add the process for the docs/manual later.

Transferred and integrated these steps partially and will do some proofreading of them tomorrow! Thank you!

I updated the gist with a few fixes to the previous section, and a new section for the docs/manual update.
We'll go through that process together with @Calinou next week, so I suggest waiting for that so we can do further tweaks on the gist before integrating it in the contributing docs.

Great! Then I'll take a look at a general new pass on this one when that's ready

Do you have any updates on the translation process? Looking at potentially doing some work on this PR this week

The gist linked above is complete. We ran through the docs process with @Calinou and I don't recall that it required further adjustments. So you can finish integrating it.

Great! Then I'll look at that today and tomorrow

AThousandShips · 2026-07-01T14:11:44Z

@mhilbrunner @skyace65 Would appreciate some help outlining these processes here

This is going to be a mhilbrunner thing. I haven't done release day changes (making the new branch) before.

Hai. I can indeed provide at least some of these (especially the docs; translations are the big one where I lack the practical experience, although I've tried to follow along when Akien patiently explained the process to me :P)

I'm pretty swamped currently, but I'll try to find a minute to contribute in whatever form works best... maybe a PR to this PR?

Also thanks for taking the initiative and working on this, its been sorely needed for a long while.

Thank you! And we can work out how to best provide the details, perhaps a gist? Or if someone else who is familiar with the details can help as well

But this PR will take a while to get through my own tuning and adding sections so no rush!

@mhilbrunner are you able to look at some details for this? Trying to get some of the areas of this filled in

AThousandShips · 2026-07-03T14:46:49Z

Updated from the outlines above, will look at adding the translation content next week and tuning some of the other sections, thank you @Repiteo!

AThousandShips · 2026-07-21T13:59:28Z

CC @dsnopek @BastiaanOlij any steps critical for the extension/godot-cpp side that would be good to document here?

dsnopek · 2026-07-29T11:52:04Z

any steps critical for the extension/godot-cpp side that would be good to document here?

It could make sense to add some notes to the release_cycle_checklists.rst for godot-cpp:

On every -beta, -rc and 4.x.0-stable release, we update the extension_api.json and gdextension_interface.json for that Godot minor version
- We don't do this for 4.x.1, 4.x.2, etc patch releases, because that would lock godot-cpp to requiring that specific patch release or above
- This is has traditionally been done via a commit directly to master, without a PR (although, a handful of times it was done via a PR, usually when some other part of it needed review)
- Here's an example.

I think that's all that would fit in with what's in the PR so far. It may be worth nothing somewhere that we don't allow changes to gdextension_interface.json in patch releases, but that doesn't seem to fit in here

AThousandShips · 2026-07-29T11:53:13Z

Thank you will look at integrating that and doing some restructuring today!

Edit: Will get back to this on Monday

AThousandShips · 2026-09-24T15:07:27Z

Integrated the rest of the translation workflow with some adjustments will do a deeper proofread of it tomorrow and look at some of the other parts of the workflow

AThousandShips · 2026-09-25T12:58:49Z

Did some proofreading of the translation section and it should be good to go, will take a new pass over the rest of the changes next week and try to fill in the missing areas

AThousandShips · 2026-10-01T12:17:39Z

+
+.. _doc_release_documentation_upgrading:
+
+Upgrading from X to Y


@raulsntos could you assist in outlining this, perhaps we can create a template and some details on how this is tracked and organized, thanks!

I usually copy the previous page and remove the contents of the "Breaking changes", "Behavior changes", and "Changed defaults" sections (I remove the tables but keep the intro text), to use it as a template.

To write the actual page contents, I look at various things:

The GDExtension validation files in misc/extension_api_validation.
Changes to property types are usually ignored, since they don't affect the scripting API surface, only the editor. The actual property type is the type used by the getter/setter methods.

The documentation files in doc/classes.
Mostly to look for changed defaults.

The C# compatibility suppressions generated by the ApiCompat tool.
This requires making changes¹ to the .csproj files and then building the engine and C# assemblies.
Often these changes match the ones in the GDExtension validation files, but it should be a smaller subset since API with compat methods would not be listed.
Sometimes it may highlight breaking changes exclusive to C#, like changes to type metadata (e.g. int32 -> int64), that are not usually considered breaking changes for GDExtensions.

Looking through those files, I collect the changes and then I find the PRs that introduced them. The GDExtension validation files already list the PR number, but for changes to the documentation files I have to use git blame to find the PR.

Then, I look through those PRs to try and understand what the changes are about, and whether the breaking changes can be avoided. In some cases, I may ask the team that owns the code for additional details.

Finally, I make the table with the changes and fill the columns. In some cases, I may create a Godot project to verify that the column values are correct.

The table categories and their order is mostly arbitrary and based on feels, but I do usually look at previous pages to try and keep it somewhat consistent. The contents within the tables are sorted alphabetically.

It may be worth noting that, in the past, I've usually waited until the RC before writing the migration page, because breaking changes keep being made up until (and sometimes after) the RC phase.

I also rely heavily on area maintainers to review the changes listed, and specially to fill the "Behavior changes" section which I have no way of collecting.

Let me know if this was useful or if you wanted something else.

Footnotes

See https://github.com/godotengine/godot/pull/77183 ↩

Thank you! I'll take a closer look next week and see about writing something from it and I'll ping you again if I have any further questions

Updated with an outline based on this and will do a second pass over it next week

AThousandShips · 2026-10-21T14:55:17Z

+.. note::
+
+    This section is targeted at maintainers. For a general outline of the release
+    cycle, please see :ref:`doc_release_cycle_outline`.


Now in a separate PR:

[WIP] Add release cycle outline page #136

Will leave it here for now and adjust depending on what merges first

Checklists for the release process

AThousandShips added enhancement New feature or request content:new page Issues and PRs related to creation of new documentation pages for new or undocumented features labels Jul 1, 2026

AThousandShips commented Jul 1, 2026

View reviewed changes

AThousandShips requested review from Repiteo, akien-mga, mhilbrunner and skyace65 July 1, 2026 14:12

Repiteo reviewed Jul 1, 2026

View reviewed changes

Comment thread other/release_management/release_cycle_checklists.rst Outdated

Repiteo reviewed Jul 1, 2026

View reviewed changes

Comment thread other/release_management/release_cycle_checklists.rst Outdated

AThousandShips force-pushed the release_cycle_overview branch from 359938a to 4000c81 Compare July 3, 2026 14:46

AThousandShips force-pushed the release_cycle_overview branch 2 times, most recently from a7a0b58 to 0cb5fc9 Compare July 9, 2026 13:52

AThousandShips force-pushed the release_cycle_overview branch 3 times, most recently from a89b7fc to db55fb2 Compare August 7, 2026 14:59

AThousandShips force-pushed the release_cycle_overview branch from db55fb2 to 4000d29 Compare September 24, 2026 15:06

AThousandShips force-pushed the release_cycle_overview branch 3 times, most recently from e10e6ed to f009483 Compare September 25, 2026 12:58

AThousandShips force-pushed the release_cycle_overview branch from f009483 to 1329a78 Compare September 30, 2026 18:02

AThousandShips commented Oct 1, 2026

View reviewed changes

AThousandShips force-pushed the release_cycle_overview branch from 1329a78 to c216b25 Compare October 8, 2026 14:20

AThousandShips force-pushed the release_cycle_overview branch from c216b25 to dab4699 Compare October 21, 2026 14:47

AThousandShips mentioned this pull request Oct 21, 2026

[WIP] Add release cycle outline page #136

Draft

AThousandShips commented Oct 21, 2026

View reviewed changes

Add documentation for the release cycle

5dbc2aa

Checklists for the release process

AThousandShips force-pushed the release_cycle_overview branch from dab4699 to 5dbc2aa Compare October 23, 2026 13:38


		.. _doc_release_documentation_upgrading:

		Upgrading from X to Y

Conversation

AThousandShips commented Jul 1, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mhilbrunner Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

AThousandShips commented Jul 3, 2026

Uh oh!

AThousandShips commented Jul 21, 2026

Uh oh!

dsnopek commented Jul 29, 2026

Uh oh!

AThousandShips commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AThousandShips commented Sep 24, 2026

Uh oh!

AThousandShips commented Sep 25, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Footnotes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

mhilbrunner Jul 2, 2026 •

edited

Loading

AThousandShips commented Jul 29, 2026 •

edited

Loading