From 9848d64e436f84afc915b0fabd61874261f68260 Mon Sep 17 00:00:00 2001
From: Jeff Billimek <jeff@billimek.com>
Date: Tue, 14 Apr 2020 12:59:12 -0400
Subject: [PATCH] document breaking change (#202)

---
 charts/blocky/Chart.yaml |  2 +-
 charts/blocky/README.md  | 26 ++++++++++++++++++++++++++
 2 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/charts/blocky/Chart.yaml b/charts/blocky/Chart.yaml
index d096bc51..6137a147 100644
--- a/charts/blocky/Chart.yaml
+++ b/charts/blocky/Chart.yaml
@@ -2,7 +2,7 @@ apiVersion: v1
 appVersion: "v0.6"
 description: DNS proxy as ad-blocker for local network
 name: blocky
-version: 2.3.0
+version: 3.0.0
 keywords:
   - blocky
   - dbs
diff --git a/charts/blocky/README.md b/charts/blocky/README.md
index 9579c3d0..e4db319d 100644
--- a/charts/blocky/README.md
+++ b/charts/blocky/README.md
@@ -46,3 +46,29 @@ Alternatively, a YAML file that specifies the values for the above parameters ca
 ```console
 helm install --name blocky -f values.yaml billimek/blocky
 ```
+
+## Upgrading an existing Release to a new major version
+
+A major chart version change (like 2.2.2 -> 3.0.0) indicates that there is an
+incompatible breaking change needing manual actions.
+
+### Upgrading from 2.x.x to 3.x.x
+
+Due to the renaming of the service port, an upgrade-in-place will not work.  The following are possible approaches to solve this:
+
+#### Helm force upgrade
+
+```sh
+helm upgrade --force
+```
+
+#### Delete the existing `blocky` service prior to upgrading
+
+```sh
+kubectl delete svc/blocky
+```
+
+#### Remove the existing blocky chart first
+
+This is the 'easiest' approach, but will incur downtime which can be problematic if you rely on blocky for DNS
+