Netlify-cms: Deprecate inconsistent configuration parameters case

[hanneskuettner]

Is your feature request related to a problem? Please describe.

Right now there are two case styles used for a lot of exposed configuration parameters.
camelCase and the apparently preferred snake_case. It sometimes makes it tedious to remember the correct casing for a parameter.

Internally the camelCase is used a lot as is typical for JS.

We should provide a backward compatible deprecation of one or the other casing.

Right now I could find the following inconsistencies:

• Collection
  
  
  
  • sortableFields
  
  
• Date[time] Widget
  
  
  
  • dateFormat
  
  
  • timeFormat
  
  
• Markdown Widget
  
  
  
  • editorComponents
  
  
• Number Widget
  
  
  
  • valueType
  
  
• Relation Widget
  
  
  
  • displayFields
  
  
  • searchFields
  
  
  • valueField
  
  
  • optionsLength
  
  

Which ones am I missing?

Describe the solution you'd like

Deprecate the public camelCase parameters and replace them with their snake_case equivalent in a backwards compatible fashion through wrapper functions.

Describe alternatives you've considered

Deprecate the public snake_case parameters and replace them with their camelCase equivalent in a backwards compatible fashion through wrapper functions. This would lead to consistent JS code but be a lot more work.

Additional context

[andreascm]

Hi, I'm interested in working on this. Although I'm not really clear about what do you mean by wrapper functions. Do you mean something like this?

As Is
const dateFormat = field.get('dateFormat');

To Be

const dateFormat = (field.get('dateFormat') == null) ? field.get('date_format') : field.get('dateFormat');

or

getDateFormat(field) {
    (field.get('dateFormat') == null) ? field.get('date_format') : field.get('dateFormat');
}

const dateFormat = getDateFormat(field);

[erezrokah]

Thanks @andreascm, I think instead of wrapper functions, we can normalise the configuration here:
https://github.com/netlify/netlify-cms/blob/d649e960f0fa1d5b7ff5c0c306b8901e3ead87f2/packages/netlify-cms-core/src/actions/config.js#L286

Meaning traverse the fields and change the casing so it is consistent in the configuration and also print a log warning when we find a deprecated casing.
Then we can update all built in usages to the new casing.
Note that we would need to keep both casings in the configuration for now as not to break custom widgets/preview templates.
Also, we would need to update the docs with the new casing.

[andreascm]

@erezrokah do you recommend to use camelCase or snake_case for the exposed configuration parameters?
Aside from the mentioned inconsistencies, I found one more, which is pickerUtc field in Datetime Widget. Seems like that is all the camelCase options that exist in the current configuration.

[erezrokah]

Thanks @andreascm, I think that since most options are snake_case that should be the casing for configuration options.

[andreascm]

Regarding updating the documentation, I'm thinking about putting a deprecation notice on the affected documents as well
Something like the following:

configuration-options.md

_Deprecation notice: the sortableFields option has been deprecated and will be removed in the next major release. Please use the sortable_fields option instead._

datetime.md

_Deprecation notice: the dateFormat, timeFormat, and pickerUtc options have been deprecated and will be removed in the next major release. Please use the date_format, time_format, and picker_utc options instead._

@erezrokah what do you think?

[erezrokah]

Just to confirm, the docs will have the new casing but with a notice about the old casing? That might be confusing for new users that are not familiar with the old casing.

Since we make sure both methods work, maybe we can just keep the new casing in the docs to avoid confusion?

[andreascm]

Okay, then I won't put the deprecation notice. Do we need to notify users about the change in casing? If yes, do I need to add any further info in the docs?

[erezrokah]

Okay, then I won't put the deprecation notice. Do we need to notify users about the change in casing? If yes, do I need to add any further info in the docs?

Since we're not breaking anything I think we're good. Before the next major version we'll have a dedicated changelog for all the breaking changes in one place and possibly a migration guide.