Breaking changes for version 11

[AtlasAutocode]

I would like to discuss how we can reduce code problems and make maintenance easier without causing too many problems for users that depend on the flutter quill editor.

1. The current code provides a necessary and very useful method of rich text display and editing. We want it to continue to be useful to the many users.

2. There have been many improvements and corrections to the code which have increased its complexity and made it harder to maintain the code. In many cases, old code has been bypassed and is no longer being used within the editor but may be being used by user's code since the methods are public.

3. The next major version would provide a good opportunity to clean up the code, remove dead code, simplify the code, improve documentation and testing. Such actions will be expected to cause breaking changes.

Clean up deprecated code

1. Remove deprecated code to remove code that is no longer being used.

2. In some cases, deprecating code was used as a means of alerting users that the code will be removed in a future version and providing an alternate. This code should be deleted.

Unused or incorrect code

1. There are parts of the code that are not used by the QuillEditor and do not appear to have a useful function. Perhaps they were used in the past but more recent updates and bug fixes have caused them to become obsolete.

2. Other parts of the code appear to be incorrect, but it is possible, users are using them and depend on their (incorrect?) behavior.

3. Propose to mark these with deprecated with message to post an issue if disagree.

4. Could also make these methods private - anybody using these functions would report a breaking change and we can restore the function now that we know it is in use and correct. By making them private we would not be deleting the code, so it could be restored easily and quickly.

Any other changes

Are there any areas of the code that contributors want to make breaking changes?

How do we coordinate implementing breaking changes with release of the next version?

1. We could submit PRs and merge all when version 11 is to be released. This would mean one release with consequent issues due to breaking changes which would then be dealt with by providing documented how-to's or bug fixes.

2. We could just submit/merge each PR and possibly have a cascade of issues (probably not a good idea).

3. We could handle it as suggested in 'Unused code' - in the current version, mark as deprecated and deal with any issues. Version 11 would then convert to private methods (if possible) or delete.

Questions

1. Do we want to clean up the code?
2. Can we remove deprecated code?
3. How to proceed?

[EchoEllet]

Do we want to clean up the code?

It makes it easier for contributors to introduce changes, and easier for maintainers to memorize and understand the current code, which results in a better version of the project with fewer bugs, more features, and less time to implement, so we do want that.

Can we remove deprecated code?

We usually do it in the next breaking release, sometimes we make exceptions, I made a minor breaking change in #2106.

For this specific PR, it's a breaking change for users who import files directly outside from flutter_quill_extensions.dart. Since all files were exposed by default. I also removed some deprecated code that is no longer used and has been since 2023.

How to proceed?

Cleanup of the old code can require a breaking release, I prefer it if we deprecate the code for a while, and register what needs to be changed or improved in the next breaking release. Then introduce the breaking changes with instructions for migration in the release notes.

The project version has the same format as Semantic Versioning 2.0.0 however it doesn't conform to its guidelines, as we sometimes introduce minor breaking changes in a minor version.

[EchoEllet]

@singerdmx @AtlasAutocode @CatHood0

Labels will make filtering and listing the issues easier, I will label issues from now on with priority, platform (if it's a platform-specific issue), whatever if it's already fixed or duplicated issue, we will need more labels later, such as confirming if the issue can be reproduced or waiting for response from the contributor.

See an example issue where labels were used #2243

[AtlasAutocode]

Looks good. Essentially you are proposing a triage process to prioritize reported issues as well as identify which if us is the best qualified to review the issue (subject to time availability, of course). Since I mostly work with desktop (windows but also mac) and seem to have spent time with the user selection aspects of attributes (as opposed to rendering?), I would volunteer for those but would always defer to another if they have more commitment to the issue (thankyou contributors!).

One question is: who will apply the label? If users will apply them, then Keep-It-Simple. In any event, users will see the labels so we should always choose labels that show how much we care about the issue, etc. We should also consider a rapid response to issues (not necessarily a fix!). I have always found that users are very patient when they know they have been heard and their problem has been registered. When they get no response, or acknowledgement, they get angry....

[EchoEllet]

I would volunteer for those but would always defer to another if they have more commitment to the issue

If a maintainer wants to fix it, they can assign themselves to the issue so the others know someone working on it. If a contributor wants to work on it and it's a big change, we may want to discuss it before let them introduce too many changes and then reject all of them. Should leave a note in README.md and contributing page.

If users will apply them

If they use the provided template, we can give them the option to select on which platform it and then a label will be automatically assigned, if it's a priority label, we should manage those kind of labels instead, some users don't use the template or don't select which platforms the issue persist, we will update them once reported, it will be time-consuming to label 300 issues once at a time, instead should label them when we first see the report.

[EchoEllet]

The project version has the same format as Semantic Versioning 2.0.0 however it doesn't conform to its guidelines, as we sometimes introduce minor breaking changes in a minor version.

@AtlasAutocode @CatHood0 @singerdmx

I was wrong about this, I had forgotten the fact that Pubspec confirms and enforces usage of Semantic Versioning, it always uses the latest compatible minor version whatever if this is an app or library package. I did realize that even making changes like requiring additional setup in platform runner that prevents building the project is also a breaking change, it even did happen when we used a plugin, see flutter_inappwebview #2298. Even if we introduce support for a platform, we need to ensure existing projects are able to be built without touching them, we need more tests in CI to build some open-source apps with the latest version of flutter_quill before publishing a new version.

We have introduced breaking changes in minor versions, we should instead release any breaking change (even if very minor) in major releases, reaching version 100.0.0 is not important to the end-user or developer, and should not be a priority for our case.

Noticed that we have a reason to remove YouTube support in 10.8.0 since it caused issues not from our end, and releasing a breaking change release will force users to use outdated version of the project until their related packages get updated too.

[EchoEllet]

Update: The branch release/v11 has been created, mainly to not introduce breaking changes in a non-breaking release to fix a lot of issues that require breaking change, #2322 is the first PR to merge to that branch. So I will ensure as much cleanup while making it easier to migrate.

I preferred to introduce it later once we have more time though even after #2230, it looks like additional changes are required in AndroidManifest.xml if super_clipboard was removed (even if quill_native_bridge wasn't there or #2230). I will start with the editor and toolbar providers, and then the controller.