Let's try to follow common practices concerning deprecation and versioning.

I haven't had the time to document this but I think as DJA we should followSemver and implement a similar deprecation policy likeEmber (which is most likely the most used JS framework with JSON API spec).

This way we have a simple migration guide for our users. We can simply say, upgrade to the latest minor version of a series (e.g. 2.6.0) and solve all deprecation warnings. In version 3.0.0 we simply remove all deprecation warnings and do nothing else (real changes follow then in a version 3.1.0 etc.).

What this mean for our pagination:

• We keep the naming ofJSONAPIPageNumberPagination till version 2.6.0
• In version 3.1.0 (or we could think of doing it in 3.0.0 as well) we makeJSONAPIPageNumberPagination deprecated and change logic ofPageNumberPagination toJSONAPIPageNumberPagination is today

This way we do not have to introduce a new arbitrary setting and have a simple migration guide for our DJA users.

What do you think?

I was assuming we were following semver.

Since 2.5.0 releasedJsonApi as the prefix, I think that should be what remains rather than an intermediate prefix ofJSONAPI, which has not made it to a release yet. This involves revertingcfe89ea from master I believe.

Restating what you said, In addition we should add deprecation warnings now (presumably for a forthcoming 2.6.0 release) that indicate that in 3.0 or 3.1:

• PageNumberPagination will change the default frompage andpage_size topage[number] andpage[size], effectively doing what JsonApiPageNumberPagination does now.
• LimitOffsetPagination will change the defaultmax_limit fromNone to100. Ditto.
• JsonApiPageNumberPagination will go away, replaced byPageNumberPagination.
• JsonApiLimitOffsetPagination will go away, replaced byLimitOffsetPagination.

I can revert theJSON_API_STANDARD_PAGINATION and so on in this PR that do more than the above.

Do you agree?

This sounds good. 👍

@sliverc This is ready for your review. I especially look forward to your thoughts regarding making a "promise" for future deprecations in release 3.0.

@sliverc I think I've done the PendingDeprecationWarnings correctly usingself.__dict__ and also tried to document how to prevent getting caught by the deprecations.

Thanks. The deprecation warnings look good now.

I tried to put myself into the shoes of an user and have a feeling they won't understand why they have to implement custom classes. We would certainly not recommend for them to do it unless they use the old parameterspage andpage_number.

To simplify the upgrade procedure for an existing user I think we should at this point not deprecateJsonApiPageNumberPagination. This way the documentation can state to move toJsonApiPageNumberPagination. Only if someone wants to keep the old parameters do they need to implement their custom pagination.

In the next release we will then deprecateJsonApiPageNumberPagination and say to move toPageNumberPagination.

Much cleaner for a user to understand what is happening.

Also how to solve deprecation needs to be part of the CHANGELOG and not hidden in the documentation.

I haven't written any detailed review because I think there might be a bit too many back and forth. Is it OK if I push to this PR? Would be more efficient and then you can look whether you agree with the changes.

@n2ygk I have adjusted the code and clarified changelog how to migrate. Does it look ok to you?

Do you see anything else which we need to do before releasing 2.6.0? Otherwise would I suggest we do a release and just short after follow up with a 3.0.0 release where we remove all deprecation warnings and deprecate JsonApiPageNumberPagination and JsonApiLimitOffsetPagination + changing defaults of PageNumberPaginiation and LimitOffsetPagination.

P.S.
We should squash merge this PR to keep a clear history in master

@sliverc This looks good and ready for you to squash merge.

Before a 2.6.0 release, please let me submit two more PRs:

1. QueryParameterValidation filter backend which is a companion to the others. This just enforces that only JSON:API-defined query parameters are allowed.
2. Documentation/examples update to show use ofrest_framework.filters.SearchFilter withapi_settings.SEARCH_PARAM =filter[search]
   That should fully round out all the query param-based stuff.

I will want to get to some new exception classes that properly format the errors object but that can wait.

Thanks. Merged.

I would prefer that we don't wait for a release concerning point 1. This can be added as fully backwards compatible change at any time later one. Point 2 makes certainly sense to document before a release.