Tested, works great.

Should we add a note to the docs about this changed behavior?

Tested, works great.

Should we add a note to the docs about this changed behavior?

I don't think we should add it to the docs in this case, as the wheel up generating specifically a 4 and 5.button value in the event is mainly backwards compatibility behaviour with SDL1 and neither the historic numbers (4 & 5), the recent broken ones ( 4,6,8,10,etc & 5,7,9,11 etc), or the now returned to normal ones (4 & 5) have ever been in the docs. The recent behaviour with adding 2 is also not consistent with historic pygame behaviour.

The 'correct' modern behaviour now for handling mouse wheels is the MOUSEWHEEL event and if you are using the supportedpygame.BUTTON_WHEELUP &BUTTON_WHEELDOWN constants those have always been set to 4 & 5.

I think this just qualifies as a straight up bug for 99% of users and documenting it is just going to cause confusion for people who had no idea about the strange behaviour somewhat 'behind the scenes'.

I don't think we should add it to the docs in this case

Ok.