From 9b7f2fa7718ecad89b9cd5fdc4eb6a74bec0d2dd Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Thu, 4 Oct 2018 13:56:48 -0700 Subject: [PATCH 1/3] [DEPRECATION RFC ember-data] deprecate errors changing record state --- ...a-deprecate-errors-changing-valid-state.md | 65 +++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 text/0000-ember-data-deprecate-errors-changing-valid-state.md diff --git a/text/0000-ember-data-deprecate-errors-changing-valid-state.md b/text/0000-ember-data-deprecate-errors-changing-valid-state.md new file mode 100644 index 0000000000..0c5d5e2c24 --- /dev/null +++ b/text/0000-ember-data-deprecate-errors-changing-valid-state.md @@ -0,0 +1,65 @@ +- Start Date: 2018-10-04 +- RFC PR: (leave this empty) +- Ember Issue: (leave this empty) + +# Ember Data | Deprecate Errors changing record-state + +## Summary + +Deprecates the `add` `remove` and `clear` methods of `DS.Errors` in favor of `addError` + `removeError` and `clearErrors`. + +## Motivation + +In `ember-data`, adding, removing, or clearing errors from a record's `errors` object + will affect the validation state of the record. Previously a [soft-deprecation](https://github.com/emberjs/data/pull/3853) of + this behavior was added; however, it provided no clear path to resolution. + +By deprecating these methods entirely, and providing replacement methods that do not + affect the state of the `record`, we provide end users a clear path and a clear timeline + for resolving the deprecation, and a mechanism through with users can determine if this + change in behavior requires any additional changes in their application code. + +## Detailed design + +The warnings in `DS.Errors` `add` `remove` and `clear` will be upgraded to deprecations + targeting the next LTS `3.8`. This means the feature and these methods will be removed + in `3.9`. + +New methods will be added to `DS.Errors` that do not affect record state. `addErrors` `removeErrors` + and `clearErrors`. These methods will have the same signatures as before, listed below, where + `member` is one of `type` `id` or the property name of an `attribute` or `relationship`. + +```typescript +interface Errors { + addErrors(member: string, messages: string|Array): void; + removeErrors(member: string): void; + clearErrors(): void; +} +``` + +## How we teach this + +`DS.Errors` is not well documented today, so this is an opportunity for us to revisit and + clean up. + +## Drawbacks + +- For apps using `Errors` that do not rely on the changes to record state, this will feel like + unnecessary churn. +- The new method names may feel unnecessarily verbose + +## Alternatives + +Two alternatives were considered: + +1) upgrading the existing warning to specify that the behavior would be removed in `3.9`, + We felt this was equally un-actionable as the state of things today. +2) treating the warning as a fully complete deprecation, and removing the undesired behavior now, + as the warning has been in place long enough to be considered "complete" post the `3.4 lts` cycle. + We felt this was unfair to consumers who have had no way to act upon the deprecation or determine + if it would have any effects on their applications. + +## Unresolved questions + +None From fa2d24540cbd67dab7da04fa77184affe6bca690 Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Thu, 4 Oct 2018 14:20:32 -0700 Subject: [PATCH 2/3] grammar fix --- text/0000-ember-data-deprecate-errors-changing-valid-state.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-ember-data-deprecate-errors-changing-valid-state.md b/text/0000-ember-data-deprecate-errors-changing-valid-state.md index 0c5d5e2c24..b84dcab308 100644 --- a/text/0000-ember-data-deprecate-errors-changing-valid-state.md +++ b/text/0000-ember-data-deprecate-errors-changing-valid-state.md @@ -17,7 +17,7 @@ In `ember-data`, adding, removing, or clearing errors from a record's `errors` o By deprecating these methods entirely, and providing replacement methods that do not affect the state of the `record`, we provide end users a clear path and a clear timeline - for resolving the deprecation, and a mechanism through with users can determine if this + for resolving the deprecation, and a mechanism through which users can determine if this change in behavior requires any additional changes in their application code. ## Detailed design From 489e6b9e1a5e949f3446370eb4c0804ddc9f0d48 Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Thu, 18 Oct 2018 19:37:11 -0700 Subject: [PATCH 3/3] fix method name in description --- text/0000-ember-data-deprecate-errors-changing-valid-state.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0000-ember-data-deprecate-errors-changing-valid-state.md b/text/0000-ember-data-deprecate-errors-changing-valid-state.md index b84dcab308..5470661dbd 100644 --- a/text/0000-ember-data-deprecate-errors-changing-valid-state.md +++ b/text/0000-ember-data-deprecate-errors-changing-valid-state.md @@ -6,8 +6,8 @@ ## Summary -Deprecates the `add` `remove` and `clear` methods of `DS.Errors` in favor of `addError` - `removeError` and `clearErrors`. +Deprecates the `add` `remove` and `clear` methods of `DS.Errors` in favor of `addErrors` + `removeErrors` and `clearErrors`. ## Motivation