Merge pull request #1425 from markshannon/python-points-to-change-note

Python: Change note for new points-to implementation.

Author: Felicity Chapman

change-notes/1.21/analysis-python.md

@@ -3,8 +3,34 @@
 
 ## General improvements
 
-> Changes that affect alerts in many files or from many queries
-> For example, changes to file classification
+Points-to analysis has been re-implemented to support more language features and provide better reachability analysis.
+The new implementation adds the following new features:
+
+* Non-local tracking of bound methods and instances of `super()`
+* Superior analysis of conditionals and thus improved reachability analysis.
+* Superior modelling of descriptors, for example, classmethods and staticmethods.
+* Superior tracking of values through parameters, especially `*` arguments.
+
+A new object API has been provided to complement the new points-to implementation.
+A new class `Value` replaces the old `Object` class. The `Value` class has a simpler and more consistent API compared to `Object`.
+Some of the functionality of `FunctionObject` and `ClassObject` has been added to `Value` to reduce the number of casts to more specific classes.
+For example, the QL to find calls to `os.path.open` has changed from
+`ModuleObject::named("os").attr("path").(ModuleObject).attr("join").(FunctionObject).getACall()`
+to
+`Value::called("os.path.join").getACall()`
+
+The old API is now deprecated, but will be continued to be supported for at least another year.
+
+### Impact on existing queries.
+
+As points-to analysis underpins many queries, and provides the call-graph and reachability analysis required for taint-tracking, the results of many queries may change.
+
+The improved reachability analysis and non-local tracking of bound methods may identify new results.
+The increased precision in tracking of values through `*` arguments may remove false positive results.
+
+Overall the number of true positive results should increase and the number false negative results should decline.
+We welcome feedback on the new implementation, particularly any surprising changes in results.
+
 
 ## New queries
   | **Query** | **Tags** | **Purpose** |