Documentation for common errors

[LittleBread69]

Pygame to Pygame-CE

I noticed that there isn't any documentation for people who are transitioning from Pygame to Pygame-CE. I know that the vast majority of Pygame code runs perfectly with Pygame-CE, but the point would be to have a section that can help some developers, especially the less experienced ones, to use the optimised functions of Pygame-CE, or simply to get them away from deprecated features. As mentioned for example in #3239 .

Documentation for common errors

Oftentimes, when an error popped up, a quick search would give back no results. And, even though this might not be of everyone's interest, making a section in the documentation for common errors and how to fix them would be a great way to remove hassles.

As an example, after a lot of trial and error, I found that modernGL doesn't work on MacOS unless you specify in Pygame-CE certain attributes:
pygame.display.gl_set_attribute(pygame.GL_CONTEXT_MAJOR_VERSION, 4)
pygame.display.gl_set_attribute(pygame.GL_CONTEXT_MINOR_VERSION, 1)
pygame.display.gl_set_attribute(pygame.GL_CONTEXT_PROFILE_MASK, pygame.GL_CONTEXT_PROFILE_CORE) #this one is not necessary, but it fixes some other issues.

Again, this is just one case but it could help a lot of devs struggling with errors that are already solved by many others.

[Starbuck5]

Hello!

I agree our documentation on switching could be better, probably just a few spruced up README lines is needed.

We are 100%* backwards compatible with pygame 2.1.3, so we don't need much documentation of porting code.

*There are a few very tiny differences
**How can you be fully compatible when pygame breaks compatibility with itself? See #3321 (comment) (we had to choose between back compat with previous pygame and previous us vs compat with now pygame, we chose the former).

The issue you linked (#3239) discusses breaking changes to be made in a future pygame-ce 3.0. Breaking changes are being discussed for that, we are not making breaking changes in pygame-ce 2.x.

Your documentation for common errors section is not related to pygame-ce at all, correct? I don't think we really want to maintain a guide to moderngl in our documentation, I mean we could...

[LittleBread69]

Your documentation for common errors section is not related to pygame-ce at all, correct? I don't think we really want to maintain a guide to moderngl in our documentation, I mean we could...

It was more so that I encountered similar problems with PyOpenGL, and more and more developers are pairing Pygame-ce with Moderngl / Pyopengl. I got that error only when Pygame-ce was involved, so I thought it would be good to share a fix.

We are 100%* backwards compatible with pygame 2.1.3, so we don't need much documentation of porting code.

My problem is not the backwards compatibility with code that was written before 2.1.3, more so that Pygame non-ce is at 2.6.1.*

I am not trying to say that we should make guides for other libraries, but more so that, as pygame-ce is "relatively new" (I mean the fork), which means that there aren't many cases we could base fixes on. A lot of the time, when an error happens, it is quite unclear what to do with it, and googling it either gives no answers or gives pygame.

([W]e had to choose between back compat with previous pygame and previous us vs compat with now pygame, we chose the former)

I agree it was the correct choice, I am not asking to make pygame not backwards compatible anymore, just more accessible.

*I don't think I made myself clear, but when people who want to start to code games in Python search for pygame, they will only get pygame, not pygame-ce. Oftentimes, pygame-ce will return pygame results. My point is that many of them will code in pygame and might learn that pygame-ce offers better options, or is more stable, or whatever would make them want to transition. ie: going from pygame 2.6.1 to pygame-ce 2.5.3. Many tutorials are only done for Pygame, not pygame-ce, though I understand it's not the repository's fault.
And I know that Pygame is extremely chaotic and that it has a tendency to conflict with itself, but I hoped that it would help at least one person with their game project.

Again, this is just a suggestion/enhancement, so there's no need to worry about it.

[Starbuck5]

It was more so that I encountered similar problems with PyOpenGL, and more and more developers are pairing Pygame-ce with Moderngl / Pyopengl. I got that error only when Pygame-ce was involved, so I thought it would be good to share a fix.

gives no answers or gives pygame.

Pygame answers would work though, because we're compatible with pygame. Pygame's version number has gone up tremendously over the last 2 years but few things have actually changed or been added.

Plenty of people make games with pygame-ce and then go on the internet and call them pygame games. Several recent pygame tutorials just say use pygame-ce at the beginning. (My point being is that people see pygame-ce as interchangeable for pygame).

[LittleBread69]

I understand it better now. I might've tried to help with something that didn't require any changes.

Although I guess making documentation on how to transition from Pygame to Pygame-ce is useless, as there aren't any reasons to have your code not be interchangeable.

I wonder then if there's even a need to add documentation for common errors. (more in the sense if it has any worth)