diff --git a/1.0-Upgrade.md b/1.0-Upgrade.md
index 862be7cdf..db070f52d 100644
--- a/1.0-Upgrade.md
+++ b/1.0-Upgrade.md
@@ -13,7 +13,57 @@
 
 ## Public API changes
 
-The only breaking change in the public API (so far) is the renaming of the `KubernetesDeploy` namespace to `Krane`. Otherwise, the APIs of the major public classes (`DeployTask`, `RenderTask`, `RunnerTask`, and `RestartTask`) have not changed between 0.31.1 and 1.0.0. If you're curious about this API, check the comment-based docs on these classes or the [rendered documentation at RubyGems.org](https://www.rubydoc.info/gems/kubernetes-deploy/1.0.0/KubernetesDeploy/DeployTask).
+Besides the renaming of the `KubernetesDeploy` namespace to `Krane`, we made the public interfaces of the major public classes (`DeployTask`, `RenderTask`, `RunnerTask`, and `RestartTask`) match the CLI flag names more closely.
+
+If you're curious about this API, check the comment-based docs on these classes or the [rendered documentation at RubyGems.org](https://www.rubydoc.info/gems/kubernetes-deploy/1.0.0/KubernetesDeploy/DeployTask).
+
+#### `DeployTask#initialize`
+
+Old name | New name | Comments
+--- | --- | ---
+template_paths | filenames |
+max_watch_seconds | global_timeout | This is now a duration that can be expressed in a more user-friendly language (e.g. `30s` or `1h`)
+
+#### `RestartTask#initialize`
+
+Old name | New name | Comments
+--- | --- | ---
+max_watch_seconds | global_timeout | This is now a duration that can be expressed in a more user-friendly language (e.g. `30s` or `1h`)
+
+#### `RestartTask#run`
+
+Method signature changed from this:
+
+```ruby
+def run(deployments, selector:)
+```
+
+... to this, to maintain the convention of using keyword arguments for all the public interfaces:
+
+```ruby
+def run(deployments:, selector:)
+```
+
+#### `RunnerTask#initialize`
+
+Old name | New name | Comments
+--- | --- | ---
+max_watch_seconds | global_timeout | This is now a duration that can be expressed in a more user-friendly language (e.g. `30s` or `1h`)
+
+#### `RunnerTask#run`
+
+Old name | New name | Comments
+--- | --- | ---
+task_template | filename |
+entrypoint | command |
+args | arguments |
+
+#### `RenderTask#initialize`
+
+Old name | New name | Comments
+--- | --- | ---
+template_paths | filenames |
+max_watch_seconds | global_timeout | This is now a duration that can be expressed in a more user-friendly language (e.g. `30s` or `1h`)
 
 ## Command-line interface changes