[Example] Development philosophy

[Xrayez]

Resolves godotengine/godot-proposals#575.

The documentation lacks a thorough description on general principles which govern Godot development, which would act as introductory material for potential contributors that would like to get familiar with the development aspects that start with "Why?" rather than "How?" and "What?", as with the existing "Best practices for engine contributors" page.

This is different to "Design philosophy" as well because this is mainly targeted for people who express interest in contributing as potential engine developers, rather than developers that simply use the engine.

Why?

1. Defining the scope of a particular project is always considered a good software engineering practice.
2. The scope can more or less clearly determine what features are actually needed for Godot development.
3. Defining goals and non-goals helps to prevent GIP to overflow with proposals which are nice-to-have rather than need-to-have, as described in the GIP rules and guidelines, and instead channel this to other community maintained projects that use Godot for modules and plugin development, where discussions could have a more productive outcomes. Examples of non-productive proposals in GIP: Add a fighting game input buffer. godot-proposals#100.

I've moved the previously added "convenience over absolute performance" principle added in #3788 in this PR, so you see what I've been talking about when saying that "Best practices for engine contributors" does not provide answers to these kind of questions.

The information is taken from various sources such as news articles, reddit responses, and even IRC discussions (mostly @reduz opinions as a project founder), and of course likely includes some of my own subjective vision and/or wishful thinking. 😉

Also, this actually links the GIP repository directly in the documentation, as a main tool for evaluating what is deemed useful for Godot development, I haven't found any other link to GIP throughout Godot's documentation.

Disclaimer

This is just an example, feel free to modify and build upon this to better reflect the development philosophy in a way you see it, and add other useful information.

[NathanLovato]

After reading it, at first glance, I think there's some room to shorten the article and make it clearer and maybe more assertive.

First, I wouldn't expect people to go check a dozen linked pages. Then, it takes half of the page to get to the actual dev. philosophy. You don't need the disclaimer that there's no absolute philosophy, because community-driven and open-source are specific ways to develop software. Development moves forward by relative consensus and the users or contributors can directly steer it based on people's needs. I think you can be straight about that. I'd sum it up this way, although I'd recommend asking core developers for feedback:

1. Community-driven and consensual. The core devs aim for a relative consensus before committing to a given roadmap.
2. Development is focused on adding features that benefit most users.
3. As such, the engine favors flexibility and convenience over performance.
4. But you have low-level access and facilities to write high-performance code.
5. Contributors gain responsibilities based on their dedication to the project and how trustworthy they've proven to be.

I dunno if point 5 has a place on this page, but I added it because the page is in the Contributing section for now.

@akien-mga @Calinou what do you think? Is this correct?

I'd recommend starting with a bullet list like that in the introduction, giving a quick sense of the principles the page then develops.

Could you run your text through a prose linter? The Hemingway app would be good for you as you have long sentences. The app will highlight them in red for you and help you write more accessible English. http://www.hemingwayapp.com/

[Xrayez]

After reading it, at first glance, I think there's some room to shorten the article and make it clearer and maybe more assertive.

Clearer: yes, more assertive: not sure. We don't really want go dogmatic with this kind of document, see previous reactions:

godotengine/godot-proposals#575 (comment):

I'm not sure that a full fledged Philosophy doc is a good idea. I'm concerned that throwing around language like philosophy and ideology will lead to divisiveness.

---

First, I wouldn't expect people to go check a dozen linked pages. Then, it takes half of the page to get to the actual dev. philosophy.

It's in the interest of people themselves who'd like to contribute to the project, and it's not like that you have to go check those pages, could be optional. Making this short for the sake of it is also counter-productive in my opinion, the philosophy itself could be even expanded later (I mean, more than just 1000 words), it's just that the introduction takes more text than what I've managed to come up so far. I agree that those links might not be needed at all as the history behind the project could be even described in a separate page (I'm certainly not the one who's qualified to write that). Nonetheless, I feel like at least those articles can be kept for reference.

https://godotengine.org/article/godot-history-images
https://godotengine.org/article/as-oss-godot-is-more-than-a-game-engine
https://godotengine.org/article/retrospective-and-future

But, the entire idea of linking to external resources like that is exactly to portray the history objectively, as one might be biased to "rewrite the history" if such opportunity arises. It's about transparency. I mean, there's nothing to hide, but if you do go through those articles one-by-one, you may identify some patterns in the way Godot has been developed, that was certainly an "aha" moment for me when I read those.

---

You don't need the disclaimer that there's no absolute philosophy, because community-driven and open-source are specific ways to develop software.

I have to admit that Godot is the only open-source project I've been involved throughout those years for real, starting from a severe lack of git knowledge. In fact, godot-docs is the first open-source repository I contributed to: #338. 🙂

So, what are the odds and percentage of people that would go through a similar learning experience? Again, my ignorance itself is what probably lead to extended discussion in godotengine/godot-proposals#575. That's what I meant by "may be obvious to core developers".

I dunno if point 5 has a place on this page, but I added it because the page is in the Contributing section for now.

To be honest, I wanted to create this under the Development section rather than contributing at first, but these topics seem to share both qualities.

Could you run your text through a prose linter? The Hemingway app would be good for you as you have long sentences.

I guess on some level that's because it was specifically written that way. 😛

I'll leave this to other core developers to pick this up, in any case, this is just an example of how I personally see this, of course it may not be in alignment with opinions of the core developers, else I think wouldn't really have to create godotengine/godot-proposals#575 in the first place.

So, if you do want to describe this yourself, feel free, I think there are more experienced contributors who can document this better than me.

Feel free to build upon this, and strip off what do you think is unnecessary. I could also make any changes that you suggest, of course.

[NathanLovato]

Clearer: yes, more assertive: not sure.

My bad for writing assertive, I meant affirmative or more direct than it is now. I.e. removing parts such as there is no *absolute* philosophy behind Godot Engine development.

We don't really want go dogmatic

It's not dogmatic to say Godot is community-driven, open-source, that all development happens publicly, etc. It's a description of how development is working right now.

I guess on some level that's because it was specifically written that way. stuck_out_tongue

What I meant is you could make the sentences both shorter and clearer without changing any of the meaning. Our goal is to help people reading the docs by making the writing as simple as possible. Writing short and simple sentences helps reduce cognitive load for readers and makes the content more accessible to non-native English speakers or a younger audience. From the docs' writing guidelines:

The Godot community is rich and international. Users come from all around the world. Some of them are young, and many aren't native English speakers. That's why we must all write using a clear and a common language. For the class reference, the goal is to make it easy to read for everyone and precise.