1 files changed, 85 insertions, 0 deletions
diff --git a/nixos/doc/manual/release-notes/rl-2305.section.md b/nixos/doc/manual/release-notes/rl-2305.section.md
index ff01d7228df3..62ddb6c9530d 100644
--- a/nixos/doc/manual/release-notes/rl-2305.section.md
+++ b/nixos/doc/manual/release-notes/rl-2305.section.md
@@ -157,6 +157,9 @@ In addition to numerous new and upgraded packages, this release has the followin
 
 - conntrack helper autodetection has been removed from kernels 6.0 and up upstream, and an assertion was added to ensure things don't silently stop working. Migrate your configuration to assign helpers explicitly or use an older LTS kernel branch as a temporary workaround.
 
+- The `services.pipewire.config` options have been removed, as they have basically never worked correctly. All behavior defined by the default configuration can be overridden with drop-in files as necessary - see [below](#sec-release-23.05-migration-pipewire) for details.
+
+- `services.pipewire.media-session` and the `pipewire-media-session` package have been removed, as they are no longer supported upstream. Users are encouraged to use `services.pipewire.wireplumber` instead.
 ## Other Notable Changes {#sec-release-23.05-notable-changes}
 
 <!-- To avoid merge conflicts, consider adding your item at an arbitrary place in the list instead. -->
@@ -301,3 +304,85 @@ In addition to numerous new and upgraded packages, this release has the followin
 - The option `services.prometheus.exporters.pihole.interval` does not exist anymore and has been removed.
 
 - `k3s` can now be configured with an EnvironmentFile for its systemd service, allowing secrets to be provided without ending up in the Nix Store.
+
+## Detailed migration information {#sec-release-23.05-migration}
+
+### Pipewire configuration overrides {#sec-release-23.05-migration-pipewire}
+
+#### Why this change? {#sec-release-23.05-migration-pipewire-why}
+
+The Pipewire config semantics don't really match the NixOS module semantics, so it's extremely awkward to override the default config, especially when lists are involved. Vendoring the configuration files in nixpkgs also creates unnecessary maintenance overhead.
+
+Also, upstream added a lot of accomodations to allow doing most of the things you'd want to do with a config edit in better ways.
+
+#### Migrating your configuration {#sec-release-23.05-migration-pipewire-how}
+
+Compare your settings to [the defaults](https://gitlab.freedesktop.org/pipewire/pipewire/-/tree/master/src/daemon) and where your configuration differs from them.
+
+Then, create a drop-in JSON file in `/etc/pipewire/<config file name>.d/99-custom.conf` (the actual filename can be anything) and migrate your changes to it according to the following sections.
+
+Repeat for every file you've modified, changing the directory name accordingly.
+
+#### Things you can just copy over {#sec-release-23.05-migration-pipewire-simple}
+
+If you are:
+
+- setting properties via `*.properties`
+- loading a new module to `context.modules`
+- creating new objects with `context.objects`
+- declaring SPA libraries with `context.spa-libs`
+- running custom commands with `context.exec`
+- adding new rules with `*.rules`
+- running custom PulseAudio commands with `pulse.cmd`
+
+Simply move the definitions into the drop-in.
+
+Note that the use of `context.exec` is not recommended and other methods of running your thing are likely a better option.
+
+```json
+{
+  "context.properties": {
+    "your.property.name": "your.property.value"
+  },
+  "context.modules": [
+    { "name": "libpipewire-module-my-cool-thing" }
+  ],
+  "context.objects": [
+    { "factory": { ... } }
+  ],
+  "alsa.rules": [
+    { "matches: { ... }, "actions": { ... } }
+  ]
+}
+```
+
+#### Removing a module from `context.modules` {#sec-release-23.05-migration-pipewire-removing-modules}
+
+Look for an option to disable it via `context.properties` (`"module.x11.bell": "false"` is likely the most common use case here).
+If one is not available, proceed to [Nuclear option](#sec-release-23.05-migration-pipewire).
+
+#### Modifying a module's parameters in `context.modules` {#sec-release-23.05-migration-pipewire-modifying-modules}
+
+For most modules (e.g. `libpipewire-module-rt`) it's enough to load the module again with the new arguments, e.g.:
+
+```json
+{
+  "context.modules": [
+    {
+      "name": "libpipewire-module-rt",
+      "args": {
+        "rt.prio": 90
+      }
+    }
+  ]
+}
+```
+
+Note that `module-rt` specifically will generally use the highest values available by default, so setting limits on the `pipewire` systemd service is preferable to reloading.
+
+If reloading the module is not an option, proceed to [Nuclear option](#sec-release-23.05-migration-pipewire).
+
+#### Nuclear option {#sec-release-23.05-migration-pipewire-nuclear}
+If all else fails, you can still manually copy the contents of the default configuration file
+from `${pkgs.pipewire.lib}/share/pipewire` to `/etc/pipewire` and edit it to fully override the default.
+However, this should be done only as a last resort. Please talk to the Pipewire maintainers if you ever need to do this.