From 9605ff3bf5754c3932da851d8929d0c78f68b9f5 Mon Sep 17 00:00:00 2001
From: Jannis R <mail@jannisr.de>
Date: Tue, 10 Dec 2019 20:43:45 +0100
Subject: [PATCH] "migration to 5" guide, remove "migrating to 3" guide :memo:

---
 docs/migrating-to-3.md | 70 ------------------------------------------
 docs/migrating-to-5.md | 51 ++++++++++++++++++++++++++++++
 docs/readme.md         |  2 +-
 3 files changed, 52 insertions(+), 71 deletions(-)
 delete mode 100644 docs/migrating-to-3.md
 create mode 100644 docs/migrating-to-5.md

diff --git a/docs/migrating-to-3.md b/docs/migrating-to-3.md
deleted file mode 100644
index ebcee057..00000000
--- a/docs/migrating-to-3.md
+++ /dev/null
@@ -1,70 +0,0 @@
-# Migrating to `hafas-client@3`
-
-## New `User-Agent` parameter
-
-Pass an additional `User-Agent` string into `createClient`:
-
-```js
-const createClient = require('hafas-client')
-const dbProfile = require('hafas-client/p/db')
-
-const client = createClient(dbProfile, 'my-awesome-program')
-```
-
-Pick a name that describes your program and – if possible – the website/repo of it.
-
-## If you use the `journeyLeg()` method…
-
-…change the `journeyLeg(id, lineName)` call to `trip(id, lineName)`. c8ff217
-
-## If you use the `journeys()` or `trip()` methods…
-
-- …instead of `journey.departure`, use `journey.legs[0].departure`. 005f3f8
-- …instead of `journey.arrival`, use `journey.legs[last].arrival`. 005f3f8
-- …rename `opt.passedStations` to `opt.stopovers`. ebe4fa6
-- …rename `leg.passed` to `leg.stopovers`. 6611f26
-- …rename `leg.stopovers[].station` to `leg.stopovers[].stop`. 3e672ee
-
-## If you use the `journeys()` method and `opt.when`…
-
-…use `opt.departure` instead. Use `opt.arrival` to get journeys arriving before the specified date+time. This replaces the `opt.when` & `opt.whenRepresents` options from `hafas-client@2`. c82ad23
-
-## If you use the `journeys()` and `opt.polylines` or `trip()` and `opt.polyline`…
-
-…`leg.polyline` will be [parsed for you now](https://github.com/public-transport/hafas-client/blob/f6c824eecb459181ea90ddf41bf1a1e8b64539ec/docs/journey-leg.md#polyline-option).
-
-## If you use the `departures()` method…
-
-…rename `departure.journeyId` to `departure.tripId`. 2e6aefe
-
-## If you use the `location()` method…
-
-…change the `location(id)` call to `station(id)`. 665bed9
-
-## If you use the `radar()` method…
-
-- …change the `radar(north, west, south, east)` call to `radar({north, west, south, east})`. 40b559f
-- …rename `movement.journeyId` to `movement.tripId`. 2e6aefe
-
-## If you use `hafas-client` with a custom profile…
-
-- …write your profile in [the new format](writing-a-profile.md). Then, you can pass it into `hafas-client` just like before. #32/b7c1ee3
-- …rename the `profile.journeyLeg` flag to `profile.trip`. 8de4447
-
-## If you use `hafas-client` with custom parse functions…
-
-…change the following parsers to the `parse…(profile, opt, data)` signature. 8881d8a/b6fbaa5
-
-- `parseDeparture`
-- `parseJourney`
-- `parseJourneyLeg`
-- `parseLine`
-- `parseMovement`
-- `parseLocation`
-- `parseNearby`
-- `parsePolyline`
-- `parseStopover`
-
-## If you use `station.lines` array anywhere…
-
-…add the `stationLines: true` option to the method call, e.g. `hafas.departures('123', {stationLines: true}). cabe5fa
diff --git a/docs/migrating-to-5.md b/docs/migrating-to-5.md
new file mode 100644
index 00000000..18df3281
--- /dev/null
+++ b/docs/migrating-to-5.md
@@ -0,0 +1,51 @@
+# Migrating to `hafas-client@5`
+
+## If you use `journeys()`…
+
+…with the `walkingSpeed` option and a custom profile, add `journeysWalkingSpeed` to your profile. 937583e
+…without the `results` option, but *expect* a certain number of results, you must pass `results` now. 0045587
+
+## If you use `departures()`/`arrivals()` with the [BVG profile](../p/bvg)…
+
+With the latest protocol version, the BVG endpoint doesn't support these options anymore:
+
+- `stopovers` – Fetch & parse previous/next stopovers? Default: `false`
+- `includeRelatedStations` – Fepartures at related stations, e.g. those that belong together on the metro map? Default: `true`
+
+2d72391
+
+## If you use a custom profile…
+
+Let's assume you have parse function looking like this:
+
+```js
+const createParseLine = (profile, opt, data) => (rawLine) => {
+	const operator = data.operators[rawLine.oprX] || null
+	if (operator && operator.name === 'foo') {
+		return {
+			type: 'line',
+			name: 'really special tram line',
+			mode: 'tram',
+			product: 'special-tram',
+			operator
+		}
+	}
+	return defaultParseLine(rawLine)
+}
+```
+
+Adapt your parse function like this:
+
+```diff
+const createParseLine = (profile, opt, _) => (rawLine) => {
+-	const operator = data.operators[rawLine.oprX] || null
++	const operator = rawLine.operator || null
+```
+
+See also [`#127`](https://github.com/public-transport/hafas-client/pull/127).
+
+If you use `icons` in `parseWarning`/`parseHint`, adapt the function(s) to take an object `data` as the first argument. You can access the list of *parsed* icons via `data.icons`, *parsed* warnings via `data.warnings`, etc. a229205 b36f0e3
+
+## Other breaking changes
+
+- `journey.price` will be `null` if there's no pricing data returned by the endpoint, instead of `{amount: null}`. 8fe277d
diff --git a/docs/readme.md b/docs/readme.md
index d403b727..a3f42520 100644
--- a/docs/readme.md
+++ b/docs/readme.md
@@ -13,8 +13,8 @@
 
 ## Migrating from an old `hafas-client` version
 
-- [`2` → `3` migration guide](migrating-to-3.md)
 - [`3` → `4` migration guide](migrating-to-4.md)
+- [`4` → `5` migration guide](migrating-to-5.md)
 
 ## Throttling requests