OptionList breaks backwardscompatibility from 0.4.1 to 0.4.0

[Kuna42]

Describe the bug

Keywords are incompatible from 0.4.0 to 0.4.1

Steps to reproduce

1. Write code with keywords in toga 0.4.0
2. Update to toga 0.4.1

Expected behavior

The keyword should be recognized.

Screenshots

No response

Environment

• Operating System:
• Python version:
• Software versions:
  • Briefcase:
  • Toga: 0.4.0 -> 0.4.1

Logs

TypeError: OptionList.append() got an unexpected keyword argument 'text'

Additional context

The Documentation of 0.4.1 shows, what breaks the backwards compatibility.
The keyword is now text_or_item instead of text

I would favour the keyword item if an OptionItem and text if it is a string.

[freakboy3742]

Yes, the first argument to append() has changed; that should have been noted in the release notes.

We could potentially add a text keyword argument for backwards compatibility; however, given that 0.4.1 has been released with this change in place, it would be an affordance that would get minimal use, as anyone depending on the argument name would have made the update as part of upgrading to 0.4.1.

We're not going to add separate text and item arguments; the argument is positional, not intended to be passed in as a keyword. Breaking the argument into two parts has no benefits, and significantly increases the complexity of the method as we need to handle "provides both" and "provides neither" use cases, as well as type checking that text and item have been provided as the right types.

There's potentially a need for a policy decision here about backwards compatibility when it comes to positional and keyword arguments; as part of that change, we should be enforcing the use of keyword arguments in more of the API. I've opened #2308 to track this.