I Tried Correcting One Word in the Godot Engine Documentation

I won’t do it again.

A lot of the game development community looks at Godot as the little game engine that could, and I’m no different. Since its public release in 2014, Godot has gradually become the go-to destination for developer rebels who want to stick it to Unity, Epic, and every other engine and tool developer looking to regulate how its users create.

But as with any unwieldy band of rebels, the community can get a little…uhh…chaotic.

How this goes in ideal circumstances

To give a frame of reference for this story, let me quickly describe my first experience contributing to the open-source .NET MAUI documentation. A couple of months ago, for the first time in several years, I had an idea for a small software tool I wanted to create to help me work a bit more efficiently. I’ve been developing software long enough to know that what’s best supported in the moment is a lot more important than what you’re used to using, so when I saw Microsoft throwing most of its eggs into the .NET MAUI basket, I figured I should at least get familiar with it, and this was a great opportunity.

This is how I ran into a bit of an odd sentence in the docs on GitHub. It read something like this:

When a control lists multiple items, such as a ListView, is bound to an ObservableCollection, the two work together to automatically keep the list of items in sync with the collection.

Don’t spend too much time trying to parse that, it doesn’t quite make sense. When I figured out what it was trying to say–some version of: When a control which lists multiple items–I thought, great, here’s a quick chance to contribute to open source.

And it was! I took time to carefully go over Microsoft’s contribution guidelines (at least past the section where they explain how they want small documentation changes made), I forked the repository, made the change right in the browser, and sent the commit as a pull request. The next morning I received two GitHub notifications by email.

“<Username> has approved this pull request.”

and

“Merged <pull request> into Main.”

Done and done.

How this went with Godot

I have one abandoned project (out of many) that particularly nags at me because it involved a friend. If you’ve followed my podcast, GameDev Breakdown, you know we came up with a cool new format where I find a friend willing to commit some time and we dream up a small game project before actually trying to make it. You may also know that we sort of crashed and burned on the very first one as the pod went on hiatus so I could tend to some real life and real work issues. I hate this because the guest was Boss Fight author Sebastian Deken who is a very nice guy and was beyond excited about the project and the idea we came up with. Worse, he had the strength of character to leave Twitter after Elon ransacked it and our interactions trailed off completely. I’d still love to make that project happen, and Godot was my engine of choice.

While visiting the docs to learn how to port the project from the late version 3s to 4.2+, a sentence about TileMaps stopped me in my tracks. See if you can spot the word, it’s still very much there.

A TileMap may have several layers, layouting tiles on top of each other.

Now, I don’t even particularly care for Microsoft, and I took the time to help them out with a missing “which.” I felt I could do no less for Godot about the word “layouting” which is not a word at all.

I opened Godot‘s documentation contribution guidelines and my determination was tested immediately.

Godot’s docs are divided into the Class Reference and the Manual. The best way to tell the difference, if I even understand it yet, is that if you see a list of properties and methods on the page, you’re looking at the Class Reference. To Godot’s credit, the more-technical Class Reference pages are described and explained very well, so it’s not always immediately clear which type of documentation page you’re looking at.

The difference becomes important for contributors, though, because they need to contribute edits to the Manual in the correlating RST files using a text editor while the Class Reference is built automatically from XML files in a totally different location, meaning changes to Class Reference RSTs (even if they made it through the review process) would likely be overwritten. My TileMaps correction would need to go in a Class Reference file.

I stuck with it, and managed to get a pull request sent for the correct (?) file suggesting a change from the word “layouting” to “layering.” As best I can tell, this is probably what the original author intended. Done and done.

When I submitted the PR, I noticed the Godot repo has over 2,700 pull requests open.

That’s that, I thought. There’s no way I will ever hear about this again.

Wrong!

The first message came less than an hour later.

“Thanks for opening a pull request!”

My Pleasure.

“Please amend the commit to use a human-readable commit message (git commit –amend). This way, people reading the Git log can easily figure out what’s going on 🙂”

Oh.

I was pretty sure I had added human-readable wording to everything, especially the Commit description which was many words longer than the actual change that needed to be made. Upon review, I realized the Commit title, which is admittedly very important when browsing a repo, was GitHub’s default, “Updating TileMaps.XML.” I’d argue that’s human-readable and that a much longer title would get truncated, but that’s on me. I changed it.

Simultaneously, the same user left a comment on my committed change.

“What about ‘laying out’? This would be the correct form of ‘layouting’ while avoiding repetition.”

Well, layouting isn’t a word, so there’s no correct form of it. The repetition was presumably present since the dawn of TileMaps, I was just trying to stay uninvasive with this procedure. Finally, a layout or “laying out” describes how things are arranged in one layer, not stacked. I didn’t go into all that in the reply, but I did address the last point, even going as far as to say the sentence could be simplified further to say that a TileMap could contain several layers.

No further comments from this user.

A second user jumps in.

That whole line could use rewording to be honest. Neither the original or this PR’s are to my liking due to the awkward wording.

Fabulous. This is like me patching a hole in your drywall and you bringing up that you don’t like the room we’re in or my patch. That’s fine, but it doesn’t contain specific information, and I have no idea what you’d like me to do about it.

I replied.

I think there’s a big difference between the original that contained a word that isn’t real and anything that contains all real words, but that’s up to you all.

They replied.

I mean, the word in the PR is an improvement of course.

Okay. Then what are we sitting here talking about?

It doesn’t matter. I’m mentally checked out of the situation. There’s a green checkmark next to the request now and some tags about versions. I don’t know what they intend to do with it, and I do not care at this point.

Godot’s documentation says, “We always need help to improve the documentation…” I think I believe that, but I’m not sure I believe they actually want it.

What’s going on with the Godot community vibe?

It’s tempting to assume there’s just weird energy between Godot insiders and outsiders, and I’m sure it’s a factor with the steady stream of Unity refugees, but things sound even worse inside the gates.

For a relatively young engine, It seems there’s always new Godot drama, like when a guy made the mistake of suggesting a bounty program for future engine development and the discussion got so out of hand–at one point xenophobic, at another, weirdly sexual–that the whole page had to be locked and archived. That’s an old example, but a newer one can be seen on Twitter where, in June, engine creator Juan Linietsky reminded community members that affirmative action was part of the Godot community code of conduct and got positively dragged in the comments for days.

I just want to remind that, since a long time, Godot has a code of conduct and that affirmative action is part of it.

Nobody is trying to to force anyone to change their views, but you have to be respectful of it in order to engage in the community.

— Juan Linietsky (@reduzio) June 8, 2024

Unfortunately, it goes deeper.

Next time I’ll get into the fall and second rise of the Godot forums, the W4 studio fundraising controversy, and whatever else I can find. It’s really a hell of a rabbit hole.