diff --git a/docs/src/release_notes.md b/docs/src/release_notes.md
index 38bf0d779f..995d79b8e6 100644
--- a/docs/src/release_notes.md
+++ b/docs/src/release_notes.md
@@ -1 +1,8 @@
 # Release Notes
+
+Release notes contain _noteworthy_ changes between **minor** (`1.x`) releases.
+
+> These aren't strictly pinned to **tags**.
+> So a feature announced as `1.n` might already be present in a previous or added in a later **patch** (`1.x.x`) release.
+>
+> See [releases](https://github.com/carapace-sh/carapace-bin/releases) for an exact changelog.
diff --git a/docs/src/release_notes/v1.x.md b/docs/src/release_notes/v1.x.md
index 57b556cb39..deb5b921c3 100644
--- a/docs/src/release_notes/v1.x.md
+++ b/docs/src/release_notes/v1.x.md
@@ -28,6 +28,8 @@ completion:
 
 ![](./v1.x/env-spec.cast)
 
-> - Use `shift` to skip previous arguments during **positional** completion.
+> - Use [`shift`] to skip previous arguments during **positional** completion.
 > - Renamed `env.KnownEnvironmentVariables` to `env.Names`.
 > - Renamed `env.EnvironmentVariableValues` to `env.Values`.
+
+[`shift`]:https://carapace-sh.github.io/carapace-spec/carapace-spec/macros/modifier.html#shift