Make experimental API not hidden in the docs anymore

[bilhox]

This PR aims to make experimental API not hidden anymore for pygame users, the only thing changed is this :

Original message from @itzpr3d4t0r on discord :

I mean the thing is:

• We already state that experimental modules are subject to change and tell people to not rely on them for any big project
• It is well known that experimental means it's subject to change
• If we keep stuff hidden with no specific mentions other than sporadically inside changelogs (which not a lot of people ever read) very few people will actually try the experimental api and fewer bugs or ideas will be found

So yeah I'm for updating that. I don't think something like that would damage us or people in any way really (realistically speaking). Big question is who are we really hiding these from?

This is something I fully support, why should we hide experimental API from users ? How can we expect good and continuous reviews, and bug reports ?

[damusss]

I also support this. I also think the word "stuff" could be avoided (not related to this PR). Btw when are we gonna get the new docs theme? (are the bugs we saw fixed somehow?) I think that's a change that should get more attention

[damusss]

Approving since I agree and the rest of my comment is not related to this PR. Thanks :)

[ankith26]

I support the idea behind this change but I think we can sort of reorganize sections while we are at it because the current organization isn't too great IMO.

For example, why is math advanced when Vector[n] is commonly used. I also think we should come up with better and more labels than "basic" and "advanced" but I think that needs further discussion

[bilhox]

I support the idea behind this change but I think we can sort of reorganize sections while we are at it because the current organization isn't too great IMO.

I'm okay with this, but I think we can handle it in a separate PR.

[bilhox]

With these changes, I'll add a small paragraph in the front page explaining what are experimental modules and how you can import them in your code.

[bilhox]

I added a small paragraph about experimental modules in the front page :

[Starbuck5]

I think the moniker of experimental module is not useful. There are modules where we can change things, and there are modules where we can't.

scrap / camera have been experimental a significant percentage of my lifespan, yet we honor backwards compatibility on them. Why? because people are using them. I don't think they should be experimental.

Publishing the docs for WIP modules just moves more modules from the "we can change them" camp to the "we can't change them" camp.

We as contributors can design these APIs, we need to finish them and be somewhat confident in them, and then we should publish them. Lack of feedback is not our problem, lack of clear design and lacking implementation is our problem. Although I do agree that getting things used is essential testing.

So I'm -1 on this. Especially for sdl2_video. I want to be able to change that API and not have people complaining to us about it changing, which already happens despite it being clearly marked experimental and hidden!

[Starbuck5]

Also I saw a comment on discord that reminded me!

A module being experimental and a module not being auto-imported into the pygame namespace is completely orthogonal.

pygame.freetype is not experimental and is also not imported.

[rethanon]

I added a small paragraph about experimental modules in the front page :

This isn't the only way to import though is it? For example import pygame._sdl2 is valid.

[bilhox]

Also I saw a comment on discord that reminded me!

A module being experimental and a module not being auto-imported into the pygame namespace is completely orthogonal.

pygame.freetype is not experimental and is also not imported.

Yes I know there are exceptions like gfxdraw and freetype, but all experimental modules that are currently in work in progress are not auto imported.

[bilhox]

I added a small paragraph about experimental modules in the front page :

This isn't the only way to import though is it? For example import pygame._sdl2 is valid.

Yes, I can add this way. (To anyone suggesting star import, go to jail)

[bilhox]

scrap / camera have been experimental a > significant percentage of my lifespan, yet > we honor backwards compatibility on them. Why? because people are using them. I don't think they should be experimental.

Yes I fully understand this, I might need some help to determine which modules are experimental and are constantly updated.

[bilhox]

We as contributors can design these APIs, we need to finish them and be somewhat confident in them, and then we should publish them. Lack of feedback is not our problem, lack of clear design and lacking implementation is our problem. Although I do agree that getting things used is essential testing.

Lack of clear design is also a consequence of lack of feedback and real usage in a game. So I don't really agree. Therefore, we can make them visible to the public.
I also want to mention that the way in geometry module we warn people that it should not be used as it's experimental is really efficient, because there is a text at the beginning in a red square. We are not doing this in any other modules.

[rethanon]

We as contributors can design these APIs, we need to finish them and be somewhat confident in them, and then we should publish them. Lack of feedback is not our problem, lack of clear design and lacking implementation is our problem. Although I do agree that getting things used is essential testing.

Lack of clear design is also a consequence of lack of feedback and real usage in a game. So I don't really agree. Therefore, we can make them visible to the public. I also want to mention that the way in geometry module we warn people that it should not be used as it's experimental is really efficient, because there is a text at the beginning in a red square. We are not doing this in any other modules.

A similar more nicely formatted message is also there on pygame.sdl2_video (although it still confuses me, is it supposed to be pygame._sdl2.video?)

[itzpr3d4t0r]

Publishing the docs for WIP modules just moves more modules from the "we can change them" camp to the "we can't change them" camp.

I want to be able to change that API and not have people complaining to us about it changing, which already happens despite it being clearly marked experimental and hidden!

If some modules don't clearly state they're experimental and subject to change that's a whole other issue and I could see that happening.
That aside, in my opinion, why should we care in the slightest if some randos come up complaining about experimental stuff that's clearly marked as such? Literally, who cares?
Our job, as you said, is being free to make changes at will as long as we inform people of that, anything else is uninformed people on the web yapping.

Your message conveys concern about people being unhappy with changes in a category meant for experimentation, but that's a literal contradiction there! Instead (and I'm just being brief here), letting people know we're developing these experimental modules and gathering their feedback could be far more valuable. There's much more to gain than to lose.

Besides, I'd like to hear @MyreMylar 's take on this as part of the steering council.

[bilhox]

Little update after starbuck and rethanon feedbacks.

[Starbuck5]

A similar more nicely formatted message is also there on pygame.sdl2_video (although it still confuses me, is it supposed to be pygame._sdl2.video?)

I wrote that message :)
I don't think the docs systems support sub sub modules, but I'm not sure. It's pygame._sdl2.video.

If some modules don't clearly state they're experimental and subject to change that's a whole other issue and I could see that happening.
That aside, in my opinion, why should we care in the slightest if some randos come up complaining about experimental stuff that's clearly marked as such? Literally, who cares?
Our job, as you said, is being free to make changes at will as long as we inform people of that, anything else is uninformed people on the web yapping.

I want people using our library to be happy, regardless of if they are randos. And they're not randos, because literally one of our best testers did this exact thing. He updated his pygame-ce version and went to discord to complain about _sdl2 being broken in pygame-ce, he didn't read the release, he didn't re-read the docs, I tried to point him at what changed and he didn't engage at all, I had to literally show him in Python code how to change his code to work again. I don't want to do that!

Also, during my time maintaining this library I've come to the simple conclusion that users don't read. We shouldn't expect them to, it's unrealistic. Us being all high and mighty because we've designed a system that leads to them being unhappy with us because they missed or ignored a warning is not smart of us.

---

Think of us as chefs making new items for the menu at a restaurant. Feedback is an important part of the process! But we need to actually make the meal first, and be confident it in ourselves, try it ourselves. Then we can put it on the menu.

If I come up with a new soup recipe, I'm going to ask my other chefs to try it, I'm going to try it, and if we think it's ready then we'll put it on the menu.

Therefore, lets not put things on the menu (the public facing docs), if we're not confident in them ourselves, like I'm not confident in the design of _sdl2.video.

[bilhox]

I want people using our library to be happy, regardless of if they are randos. And they're not randos, because literally one of our best testers did this exact thing. He updated his pygame-ce version and went to discord to complain about _sdl2 being broken in pygame-ce, he didn't read the release, he didn't re-read the docs, I tried to point him at what changed and he didn't engage at all, I had to literally show him in Python code how to change his code to work again. I don't want to do that!

I'm not helpfulie enough in the pygame discord to say this, but it still doesn't justify why we shouldn't make them visible. I have been helping a lot of french people constantly in one of the biggest discord server about their pygame problems, they were all the same and it didn't let me be uncalm. I'm just saying basically it's not that frequent to be a problem. (just the user being edgy If I understand what you said).

[Starbuck5]

I'm not helpfulie enough in the pygame discord to say this, but it still doesn't justify why we shouldn't make them visible. I have been helping a lot of french people constantly in one of the biggest discord server about their pygame problems, they were all the same and it didn't let me be uncalm. I'm just saying basically it's not that frequent to be a problem. (just the user being edgy If I understand what you said).

Newbies having the same problems over and over again is not something we can avoid. Newbies or experienced users going into half baked APIs to achieve their goals and then being frustrated when their code breaks in the future is something we can avoid, and we should!

I'm not saying that user behaved badly, he did exactly what I'd expect a user to do.

We are the maintainers, we have a different perspective on these things than users do, it's our prerogative to deliver them things that we actually think is good and ready, and then get feedback. We shouldn't be giving them unfinished stuff and expecting disjointed preliminary feedback (w/o SDL knowledge usually) to do our API design work for us.

[Starbuck5]

I'm fine if you unprivate the docs for geometry, controller, and window, but I don't want an experimental module section in the top bar and I don't want users stumbling onto sdl2_video.

[bilhox]

My new proposal after @Starbuck5 feedbacks :

Header is left unchanged (same as before).

[bilhox]

Modules / Objects descriptions might need a little update, but now users have to scroll down the page to actually find this list. And since a little percent of people do this, it should not be a problem anymore.

[MyreMylar]

OK, this seems reasonable and cautious to me.

As per usual, our PR back log is so large it's hard to get strategic about new API and features, but I'm confident we'll get there!