orderBy: incorrect sorting of string arrays with null values

[arw-travela]

Bug, seen in angular 1.5.7, chrome 53.0.2785.143 (64-bit) (Windows) and IE11, Also Chrome on OSX.

Using $filter('orderBy')(...) with a collection that contains strings, but some entries are null, results in the entries with null being sorted as if their entries contained the string null instead.

Expected behavior is that entries with null in the sort column would be treated as blank.

Internally replacing a nonexistent value with the string null for the purposes of comparison results in an unexpected sort order.

We have confirmed that in angular 1.2.27 arrays with null entries behaves with the expected behavior, so this is an undocumented regression.

The code in https://github.com/angular/angular.js/blob/master/src/ng/filter/orderBy.js#L654-L656 that sets value = 'null' results in the unexpected behavior. The immediate fix isn't obvious, since that change was made to address a specific issue with unspecified predicates in 48e1f56.

[gkalpak]

I don't think 48e1f56 introduced this behavior. null was converted to 'null' before (see this line).

The change seems to have been introduced in a097aa9 and is documented as a breaking change in the changelog (v1.3.7).
_{(Fixing a regression with a breaking change in a patch release might not be ideal, but it is what it is.)}

So, this is indeed a breaking change, but it is documented and has not happened in 1.5.x (which is the current stable branch). I can think of the following action items:

1. Add this breaking change in the migration guide. (Since it happened on a patch release, it hasn't been documented on the migration guide - only in the changelog.)
2. Point out the special handling for null values in the orderBy docs.
3. Discuss changing the behavior of the default comparator wrt null values. (Since this would be a breaking change, it can't happen before 1.7.)

PRs are mostly welcome for (1) and (2). For (3) could you open a feature request to get the discussion started, @arw-travela

[arw-travela]

Thanks for the response; I'll work on PR(s) for the documentation updates and a feature request.

[arw-travela]

@gkalpak - Question for you on updating docs. Ideally I'd like to update the orderBy API docs for all affected versions (1.3.7 and later). Is there a process for merging forward from that point, or do I need to update each doc version individually?