search

godotengine / godot-website

The code for the official Godot Engine website. A static site built using Jekyll.
https://godotengine.org
MIT License
294 stars 142 forks source link

Add godot 4.1 release post #665

Closed NathanLovato closed 1 year ago

NathanLovato commented 1 year ago

I addressed the comments left on the shared Google doc: https://docs.google.com/document/d/1qk5sjhRBvD4UIU45O1ebegOlICQaAtDbBPlJrUnrj0U/edit.

Feel free to make any other changes directly on top of this PR

YuriSizov commented 1 year ago

Note for future me: We should probably convert all images here to webp (and also replace spaces in file names with underscores or dashes).

raulsntos commented 1 year ago

Can we include a section listing all the break compat changes?[^1]

I've been tracking breaking changes in this gist. I last checked with RC 1, but I don't expect any breaking changes to have been introduced after the first RC.

[^1]: Perhaps something similar to https://learn.microsoft.com/en-us/dotnet/core/compatibility/7.0.

NathanLovato commented 1 year ago

@raulsntos sure, these are compatibility breakages on C# specifically, right? Seeing the info, I think it'd be good to have a dedicated file or page, probably in the docs, with this table you linked to, and to include the link in the release post. If I understand correctly, it's for people who use C# in 4.0 and who are porting their project to 4.1? If so, this should you could have a paragraph like this:

If you have a Godot 4.0 project that uses C#, if you convert it to Godot 4.1, please note that some properties and methods were changed in this version and will need to be updated manually. You can see every changed method and property in the official docs: C# compatibility changes in Godot 4.1

Also, it'd be good to mention right away if that won't happen again in the future. E..g if the backwards compatibility system in GDExtension or any future development will prevent compatibility breakages. Because otherwise people may perceive that this could happen with every new release and C# in Godot may get some more bad rap.

raulsntos commented 1 year ago

these are compatibility breakages on C# specifically, right?

No, these are changes to Core so it would affect every language. Different languages handle this differently, for example in GDScript optional parameters aren't a breaking change but in C# they are. Some of the changes in the list will break GDScript too, for example the navigation changes. GDExtension is also affected, but it's in beta so breakage is expected there.

If I understand correctly, it's for people who use C# in 4.0 and who are porting their project to 4.1?

Yes, but the biggest issue is if they are using a library that was built against GodotSharp 4.0. In this case they can't fix it because the problem is not in their code, so all they can do is wait for the library to be updated or get rid of the library.

Also, it'd be good to mention right away if that won't happen again in the future.

Of course, it's not our intention to break compat and I think we have tried to avoid it. I think it's a good idea to reaffirm our commitment to this. However, I don't think we should say that it won't happen again. For example, the navigation API was marked experimental in 4.0 so breaking compat was expected there.

E..g if the backwards compatibility system in GDExtension or any future development will prevent compatibility breakages.

We have already added compat methods to C# to avoid breaking compat in 4.1 as much as possible. But some of the breaking changes were unavoidable, for example when the only thing that has changed in a method is the return type. In C# you can't have method overloads when the only thing that changes is the return type.

Because otherwise people may perceive that this could happen with every new release and C# in Godot may get some more bad rap.

While breaking compat can be disruptive, I think most users will likely not mind that much as long as the breaking changes are communicated properly. Listing the APIs that changed as well as steps to fix the broken code would allow users to upgrade easily; otherwise, the upgrade process is likely going to be a frustrating experience and that will lead to unhappy users.

That is to say, I wish we could avoid breaking compat entirely in future versions. However, if it happens, giving the users the expectation that we will always include this information in the release article, so they can see what changed and prepare accordingly, sounds like a good thing to me.

I think it'd be good to have a dedicated file or page, probably in the docs, with this table you linked to, and to include the link in the release post.

Sure, if we prefer to have it in the documentation I can do that.

NathanLovato commented 1 year ago

@raulsntos Ok that's great information. To me, all that information would be good to have along with a table in a compatibility breakage docs page. There are a couple of reasons I recommend a docs page:

  1. It's docs material, it's a technical reference of sorts.
  2. You want to be able to easily link this in the community, and not have to link the release post and scroll to find the compat. breakages.
  3. Users and the dev team will benefit from having all this info, both where compat breaks, but also reassurance that you're trying your best to avoid it and why sometimes you really can't avoid it. It would prevent potential frustration.
  4. But that much info would be heavy in a release post and break the communication with info that will not be accessible or relevant to a fairly large number of users.
YuriSizov commented 1 year ago

What we need to add is a Known Issues section, like we do in other release notes. We have a couple of candidates for it:

RedworkDE commented 1 year ago
  • The new API to define custom export configuration options can lose data on editor reload. There is a fix available and we're likely to patch it in 4.1.1

More like it doesn't (usefully) work at all currently, except for the use by the builtin C# export plugin.

YuriSizov commented 1 year ago

I've added a couple of changes on top of the PR. First one updates images and meta. I didn't end up converting PNGs to WebPs as files are already tiny and I'm afraid of introducing compression artifacts at this point. Specific changes are outlined in the commit description.

The second improves the excerpt and introduction, adds some structure to the start of highlights and adds the known issues section with the sole entry listed above.

Another review pass would be welcome, then we should be good to go.

raulsntos commented 1 year ago

Sorry for being insistent, but I think it's important to mention the breaking changes in the release post itself. I made a PR to the documentation as discussed. Can we merge it and link to it in the release post? (needs to be reviewed though).

YuriSizov commented 1 year ago

@raulsntos We still need to work on that page, but in the meantime we'll add a link to the PR itself to the article.

YuriSizov commented 1 year ago

Thanks, everyone!