Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Conversion] Add information about breaking changes in the conversion system to the migration guide #11188

Closed
Reinmar opened this issue Jan 31, 2022 · 3 comments
Assignees
Labels
release:blocker This issue blocks the upcoming release (is critical). squad:core Issue to be handled by the Core team. type:task This issue reports a chore (non-production change) and other types of "todos".

Comments

@Reinmar
Copy link
Member

Reinmar commented Jan 31, 2022

Goal: All breaking changes need some explanation with tips (if possible) on how to migrate from the previous version to the new.

The information will base on the description of a PR for #11187.

BCs that we remember now:

  • You should update to e2S when possible (story: e2E will support only a single-element output in the future, right now it supports creating multiple elements for legacy reasons)
  • Removed triggerBy
  • Recursively firing downcast events (instead of having a loop in DowncastDispatcher)

Misc:

@Reinmar Reinmar added type:task This issue reports a chore (non-production change) and other types of "todos". squad:core Issue to be handled by the Core team. labels Jan 31, 2022
@Reinmar Reinmar changed the title Add information about breaking changes in the conversion system to the migration guide [Conversion] Add information about breaking changes in the conversion system to the migration guide Feb 14, 2022
@Reinmar
Copy link
Member Author

Reinmar commented Feb 28, 2022

Since we'll also have #11268, we can be a bit more concise here. We don't need to duplicate things like "whys". But:

  • we need both things cross-linked,
  • the migration guide must not fail to mention some BC, even if that BC wasn't covered in the summary.

@Reinmar
Copy link
Member Author

Reinmar commented Feb 28, 2022

Changes

MAJOR BREAKING CHANGE (list): The ListEditing, ListUI, ListStyleEditing, ListStyleUI, TodoListEditing, TodoListUI plugins were moved to the dedicated subdirectories (list, liststyle, todolist).

High risk.

MAJOR BREAKING CHANGE (engine): Removed the Differ#refreshItem() method from the public API. Replaced by EditingController#reconvertItem() (see #10659).

Low risk.

MAJOR BREAKING CHANGE (engine): The DowncastDispatcher will throw an error if any of the model items were not consumed while converting. Read the conversion-model-consumable-not-consumed error documentation for more information.

High risk.

MAJOR BREAKING CHANGE (engine): The DowncastDispatcher#conversionApi property is no longer available. The instances of DowncastConversionApi being created at the start of conversion.

Low risk.

MAJOR BREAKING CHANGE (engine): The support for the triggerBy option for downcast helpers is removed and replaced with the new elementToStructure() options.

High risk. 

Also, not only e2S() but also the attributes and children options in e2E().

MINOR BREAKING CHANGE (media-embed): The createMediaFigureElement helper function first argument has been changed from writer object to conversionApi object.

Super low risk

MINOR BREAKING CHANGE (table): The downcast converters of the table feature has been rewritten with the use of elementToStructure() and the re-conversion mechanism. See #10502.

Moderate risk.

Other (engine): The attribute and child nodes conversion events are fired by the lowest priority handler for the insert event instead of by DowncastDispatcher itself. Closes #10376.

Other (engine): Events are fired by the DowncastDispatcher even if they were previously consumed. It's the conversion handler's responsibility to check if it can be consumed or if it was already consumed by other converters.

Moderate risk.

People might've been canceling these events because we even mentioned this in the docs. Make it clear to never cancel.

Features

It's worth mentioning some of the most important features like passing children to createContainerElement(), e2S() and children/attributes prop of e2E(), etc.

@CKEditorBot CKEditorBot added the status:planned Set automatically when an issue lands in the "Sprint backlog" column. We will be working on it soon. label Feb 28, 2022
@Reinmar Reinmar added the release:blocker This issue blocks the upcoming release (is critical). label Mar 1, 2022
@oleq oleq self-assigned this Mar 2, 2022
@CKEditorBot CKEditorBot added status:in-progress Set automatically when an issue lands in the "In progress" column. We are working on it. and removed status:planned Set automatically when an issue lands in the "Sprint backlog" column. We will be working on it soon. labels Mar 2, 2022
oleq added a commit that referenced this issue Mar 4, 2022
… createMediaFigureElement() helper API that do not make any sense (see #11188).
oleq added a commit that referenced this issue Mar 8, 2022
Docs (ckeditor5): Added information about breaking changes in CKEditor 5 v33.x. Closes #11188.
@oleq
Copy link
Member

oleq commented Mar 8, 2022

Closed in #11423.

@oleq oleq closed this as completed Mar 8, 2022
@CKEditorBot CKEditorBot removed the status:in-progress Set automatically when an issue lands in the "In progress" column. We are working on it. label Mar 8, 2022
@CKEditorBot CKEditorBot added this to the upcoming milestone Mar 8, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
release:blocker This issue blocks the upcoming release (is critical). squad:core Issue to be handled by the Core team. type:task This issue reports a chore (non-production change) and other types of "todos".
Projects
None yet
Development

No branches or pull requests

3 participants