Complete 3.0 release notes

[einarf]

Ideally we should have:

• Higher level update notes in docs. This would also work as a general migration guide.
• Complete list of changes in a changelog in the repo itself.

This is definitely not doable fir 3.0.x considering the length of the development but we should follow this strictly from 3.0.0 and up.

[DigiDuncan]

I'd love to help with this; I think having surface-level, human readable release notes for 3.0 is strictly needed. A migration guide is also up there, for me.

[einarf]

We just have to start writing something. More info can be added over time.

[pushfoo]

TL;DR: I'll start getting some useful per-module data together for this.

There's also a user from the Python Discord I'd like to credit (https://github.com/DarkLight1337) for advising on type system issues on lower Python versions.

As to the details, Griffe has some inspection tooling which can help detect API breakage. I'll give it a try tonight.

In general, we could split this up by module. The top items of concern I can think of now are:

• [x] arcade.sprite
  • [x] Sprite.draw was removed
  • [x] BasicSprite added
  • [x] Rotation direction changed
  • [x] Whatever's going on with scale
• [x] arcade.draw split and restructuring into specific submodules
• [x] Camera rework
• [x] arcade.math changes
• [x] arcade.SpriteList

[pushfoo]

Using griffe check arcade -a 2.6.7, I see the following major categories of change:

• Removed the asset constants in arcade.resources
• GUI classes were changed and had properties removed
• Sprite removed the following:
  • draw()
  • on_update() (now a unified update method)
  • set_position()
  • face_point
  • collision_radius
  • The unused repeat_countx and repeat_count_y keyword arguments
  • The texture flipping arguments (replaced by better flip_* methods on Texture)

[DigiDuncan]

Don't forget about all the changes to draw commands, namely the namespace change, and the addition if draw_rect_*.

[pushfoo]

Don't forget all the changes to draw commands

That's the stuff in the comment above this one:

arcade.draw split

I didn't make it very clear, so I'll edit that now. Ty for pointing that out.

[pawamoy]

(stalking GitHub issues)

I'd love to know if you identified breaking changes that were not detected by Griffe! Let me know here or in new issues in Griffe's repo, as you prefer ^^ And thanks for giving it a try!

[eruvanos]

Where to put it?

* GUI

  * Removed :py:class:`~arcade.gui.widgets.UIWrapper` this is now general available in :py:class:`~arcade.gui.widgets.UILayout`
  * Removed :py:class:`~arcade.gui.widgets.UIBorder` this is now general available in :py:class:`~arcade.gui.widgets.UIWidget`
  * Removed :py:class:`~arcade.gui.widgets.UIPadding` this is now general available in :py:class:`~arcade.gui.widgets.UIWidget`
  * Removed :py:class:`~arcade.gui.widgets.UITexturePane` this is now general available in :py:class:`~arcade.gui.widgets.UIWidget`
  * Removed :py:class:`~arcade.gui.widgets.UIAnchorWidget` replaced by :py:class:`~arcade.gui.widgets.UIAnchorLayout`
  * Changes to :py:class:`~arcade.gui.widgets.UIWidget`

    * Supports padding, border and background (color and texture)
    * Visibility: visible=False will prevent rendering of the widget. It will also not receive any UI events
    * Dropped :py:meth:`~arcade.gui.widget.UIWidget.with_space_around()`
    * ``UIWidget.with_`` methods do not wrap the widget anymore, they only change the attributes
    * Support nine patch information to draw background texture
    * Removed some attributes from public interface, use ``UIWidget.with_`` methods
        * ``UIWidget.border_width``
        * ``UIWidget.border_color``
        * ``UIWidget.bg_color``
        * ``UIWidget.bg_texture``
        * ``UIWidget.padding_top``
        * ``UIWidget.padding_right``
        * ``UIWidget.padding_bottom``
        * ``UIWidget.padding_left``
    * Now iterable which provides direct access to children
    * Further performance improvements

  * New widgets:
    * :py:class:`~arcade.gui.widgets.dropdown.UIDropdown`
    * :py:class:`~arcade.gui.widgets.image.UIImage`
    * :py:class:`~arcade.gui.widgets.slider.UISlider`
    * :py:class:`~arcade.gui.widgets.constructs.UIButtonRow` (`PR1580 <https://github.com/pythonarcade/arcade/pull/1580>`_ and `PR1253 <https://github.com/pythonarcade/arcade/pull/1253>`_)

  * Arcade :py:class:`~arcade.gui.property.Property`:

    * Properties are observable attributes (supported: primitive, list and dict).
      Listener can be bound with :py:meth:`~arcade.gui.property.bind`

  * All :py:class:`~arcade.gui.UILayout`s now support ``size_hint``, ``size_hint_min``, ``size_hint_max``.

    * :py:class:`~arcade.gui.UIBoxLayout` - horizontal and vertical layout
    * :py:class:`~arcade.gui.UIAnchorLayout` - layout with anchor points
    * :py:class:`~arcade.gui.UIGridLayout` (`PR1478 <https://github.com/pythonarcade/arcade/pull/1478>`_) - grid layout

[einarf]

@eruvanos You can start a new CHANGELOG.md in the repo root. Then we merge it with doc/_archive/release_notes.rst over the next days.

[einarf]

The old update notes was moved from the docs into CHANGELOG.md in the root of the repository https://github.com/pythonarcade/arcade/pull/2332

[eruvanos]

Ok, I will add my changes to it (in md format)

[einarf]

~We also need to make sure the "thank you" section includes most or all contributors.~

EDIT: Done

[DragonMoffon]

Done in changelog-v3 branch

Okay so looking at CHANGELOG.md its still deficent in a few places. Putting them here, but I'll likely update it soon.

in the contrib list update my name to DragonMoffon since that easier to find in the discord and on github.

Maybe we could also add a little section leading people to different members for specific help with different features (me with camera, eurvanos for gui, etc), but I think that maybe we shouldn't let people ping specific members on the discord if they don't have the contrib role. I personally find it quite distracting/stressful to have people trying to directly get my attention given we are all volunteers and are doing this as a side project. (I'm guilty of this myself sorry einarf)

I'm sure there is more I am missing, but this is all I could think of in 30 mins

View and View should be changed to Window and View

BREAKING CHANGES

• ~Changed Arcade's backend to no longer rely on an xy bound orthographic projection allowing for safer 3D rendering~
• ~Removed the missnamed set_viewport method from Window~

Window and View

• ~Added a fixed update method for an update with a consistent delta time~
• ~Added the fixed_rate and max_fixed_update arguments to the arcade window for controlling on_fixed_update~

Camera

• ~Created methods for creating matrices used by arcade and pyglet in rendering~
• ~Created methods for casting from screen space to world space and back.~
• ~Created a Camer2D that allows for moving, rotating, and zooming all arcade drawables without impacting collisions or performance~
• ~Created generic Orthographic and Perspective Projectors for doing custom 2D and 3D rendering~
• ~Created data packet objects for easily working with camera's~
• ~Created a protocol for creating custom projectors~
• ~Provided a default camera that automatically adapts to the active framebuffer allowing for safe use of camera context managers~
• ~Created super simple projectors for safely manipulating GL state when more complex matrices aren't needed~
• ~Created a camera shake class, and other methods for moving a camera~

Misc

• ~Generally improved typing in math methods~
• ~Add Rect type to codify the 4-tuple description of an axis aligned rectangle include many utility methods~
• ~Created the Point, Point2, Point3 type aliases for working with tuples and vectors interchangeably~
• ~Created Sequence types for all Point aliases~
• ~Provided direct access to Vec2, Vec3, Vec4, Mat3, and Mat4 from pyglet maths.~
• ~Created a GLOBAL_CLOCK and GLOBAL_FIXED_CLOCK that are powered by the window and provide a globally accessible synced time, delta_time, and frame_number.~
• ~Added a generic glsl program from rendering a gl texture to a quad for dumb rendering of a framebuffer.~

Documentation

• ~Added more complete docs on arcade's event loop~
• Added documentation for using the new Camera (STILL TO DO)
• ~Completely overhauled the platform tutorial to work with new features~

[DragonMoffon]

More I could think of

Misc

• ~Color type~
• ~The entire future folder~
• ~get_default_texture and get_default_image methods~

Breaking Changes

• THE OVERHAUL TO TEXTURE ISN'T MENTIONED
• Texture, SpriteSheet, and their associated methods aren't mentioned
• The texture atlas changes aren't well documented

[DragonMoffon]

SUPER IMPORTANT

• ~dropped python 3.8 support (did we also drop 3.9?)~

[pushfoo]

TL;DR: End users only need 3.9 but Sphinx makes me think optional dependencies may be good.

Sphinx autobuild:

• has a pile of kludges to stop it from setting itself off
• (On my system) produces multiple process forks which set each other off anyway sometimes
• needs 3.10+ because of some dependency or other: https://github.com/pythonarcade/arcade/blob/553894e398c00fc5a1421a95dca7ea6258b124ff/pyproject.toml#L43-L52

I can check what needs which Python version later. If the dependencies play out nicely, maybe we can make it optional and add a try / catch with a helpful message in make.py?