Skip to content

Potentially update deprecation warning language #395

@GuySartorelli

Description

@GuySartorelli

We've received feedback that the current language around deprecation warnings isn't as clear as we thought. The following feedback was received (numbered for easy reference):

  1. The inclusion of deprecation warnings in CMS 5.4 changelog implies that action can be taken to avoid using that code immediately
  2. Some may think that you absolutely must not use deprecated code - but in reality it being deprecated just means you should avoid using it, but can kick the can down the road until the major upgrade if you want.
  3. The "will be" in a deprecation message isn't prominent enough - if looking at a block of deprecation warnings in logs or a changelog, it's easy to miss especially since it's in the middle of the warning developers see.

To resolve 1 and 2, a blurb at the top of the Deprecated API section could explain:

  • the purpose of adding these to the changelog - that they're to give advanced warning that breaking API changes are coming
  • that only some of the deprecation warnings can be avoided by taking action in CMS 5
  • that it's best practice to avoid using deprecated code, but it's safe to use until its removal in a future major release

To resolve 3, we could add "in a future major release" at the end of the message. E.g:

- Config SilverStripe\Dev\DevelopmentAdmin.registered_controllers is deprecated. Will be replaced with "controllers" and "commands" configuration properties.
+ Config SilverStripe\Dev\DevelopmentAdmin.registered_controllers is deprecated. Will be replaced with "controllers" and "commands" configuration properties in a future major release.

Acceptance criteria

  • Update the standardised deprecation message
  • String replace all instance of this in CMS 5.4 branches
  • Update 5.4.0 changelog to add a blurb, though do not string replace notices
  • Post merge PRs, ensure all regular merge-ups are green, then merge-up all relevant branches and ensure updated deprecation notices are not accidentally merged in

PRs

Important

After merging the above, reassign to guy to merge framework up to CMS 6

Metadata

Metadata

Assignees

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions