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 follow Semver and implement a similar deprecation policy like Ember (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 of JSONAPIPageNumberPagination till version 2.6.0
• In version 3.1.0 (or we could think of doing it in 3.0.0 as well) we make JSONAPIPageNumberPagination deprecated and change logic of PageNumberPagination to JSONAPIPageNumberPagination 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 released JsonApi as the prefix, I think that should be what remains rather than an intermediate prefix of JSONAPI, which has not made it to a release yet. This involves reverting cfe89ea 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 from page and page_size to page[number] and page[size], effectively doing what JsonApiPageNumberPagination does now.
• LimitOffsetPagination will change the default max_limit from None to 100. Ditto.
• JsonApiPageNumberPagination will go away, replaced by PageNumberPagination.
• JsonApiLimitOffsetPagination will go away, replaced by LimitOffsetPagination.

I can revert the JSON_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 using self.__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 parameters page and page_number.

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

In the next release we will then deprecate JsonApiPageNumberPagination and say to move to PageNumberPagination.

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 of rest_framework.filters.SearchFilter with api_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.