From f393252a11b2973f46b77cdf772977d1a89b1998 Mon Sep 17 00:00:00 2001
From: Tim Schaub <tim.schaub@gmail.com>
Date: Wed, 20 Dec 2017 23:39:16 -0700
Subject: [PATCH] Dedicated section for notes on the circular change

---
 changelog/upgrade-notes.md | 29 ++++++++++++++++++++++++-----
 1 file changed, 24 insertions(+), 5 deletions(-)

diff --git a/changelog/upgrade-notes.md b/changelog/upgrade-notes.md
index 600eec820f..03c5b1f301 100644
--- a/changelog/upgrade-notes.md
+++ b/changelog/upgrade-notes.md
@@ -37,31 +37,50 @@ The map and sources no longer accept a `logo` option.  Instead, if you wish to a
 
 #### Replacement of `ol/Sphere` constructor with `ol/sphere` functions
 
-The `ol/Sphere` constructor has been removed.  If you were using the `getGeodesicArea` method, use the `getArea` function instead.  If you were using the `haversineDistance` method, use the `getDistance` function instead.  The `circular` method in `ol/geom/Polygon` no longer takes a sphere as the first argument.
+The `ol/Sphere` constructor has been removed.  If you were using the `getGeodesicArea` method, use the `getArea` function instead.  If you were using the `haversineDistance` method, use the `getDistance` function instead.
 
 Examples before:
 ```js
 // using ol@4
-import Polygon from 'ol/geom/Polygon';
-import Sphere from 'ol/Sphere';
+import Sphere from 'ol/sphere';
 
 var sphere = new Sphere(Sphere.DEFAULT_RADIUS);
 var area = sphere.getGeodesicArea(polygon);
 var distance = sphere.haversineDistance(g1, g2);
-var circle = Polygon.circular(sphere, center, radius);
 ```
 
 Examples after:
 ```js
 // using ol@5
 import {circular as circularPolygon} from 'ol/geom/Polygon';
-import {getArea, getDistance} from 'ol/sphere'; // note the lowercase
+import {getArea, getDistance} from 'ol/sphere';
 
 var area = getArea(polygon);
 var distance = getDistance(g1, g2);
 var circle = circularPolygon(center, radius);
 ```
 
+#### New signature for the `circular` function for creating polygons
+
+The `circular` function exported from `ol/geom/Polygon` no longer requires a `Sphere` as the first argument.
+
+Example before:
+```js
+// using ol@4
+import Polygon from 'ol/geom/polygon';
+import Sphere from 'ol/sphere';
+
+var poly = Polygon.circular(new Sphere(Sphere.DEFAULT_RADIUS), center, radius);
+```
+
+Example after:
+```js
+// using ol@5
+import {circular as circularPolygon} from 'ol/geom/Polygon';
+
+var poly = circularPolygon(center, radius);
+```
+
 #### Removal of optional this arguments.
 
 The following methods did get the optional this (i.e. opt_this) arguments removed. Please use closures, the es6 arrow function or the bind method to achieve this effect (Bind is explained here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/bind).