2 files changed, 53 insertions, 4 deletions
diff --git a/doc/languages-frameworks/maven.section.md b/doc/languages-frameworks/maven.section.md
index cc5b4e3ed799..3b5e2e14ee64 100644
--- a/doc/languages-frameworks/maven.section.md
+++ b/doc/languages-frameworks/maven.section.md
@@ -165,6 +165,39 @@ The build will fail, and tell you the expected `outputHash` to place. When you'v
 
 If your package uses _SNAPSHOT_ dependencies or _version ranges_; there is a strong likelihood that over-time your output hash will change since the resolved dependencies may change. Hence this method is less recommended then using `buildMaven`.
 
+#### Stable Maven plugins {#stable-maven-plugins}
+
+Maven defines default versions for its core plugins, e.g. `maven-compiler-plugin`.
+If your project does not override these versions, an upgrade of Maven will change the version of the used plugins.
+This changes the output of the first invocation and the plugins required by the second invocation.
+However, since a hash is given for the output of the first invocation, the second invocation will simply fail
+because the requested plugins are missing.
+This will prevent automatic upgrades of Maven: the manual fix for this is to change the hash of the first invocation.
+
+To make sure that your package does not add manual effort when upgrading Maven, explicitly define versions for all
+plugins. You can check if this is the case by adding the following plugin to your (parent) POM:
+
+```xml
+<plugin>
+  <groupId>org.apache.maven.plugins</groupId>
+  <artifactId>maven-enforcer-plugin</artifactId>
+  <version>3.3.0</version>
+  <executions>
+    <execution>
+      <id>enforce-plugin-versions</id>
+      <goals>
+        <goal>enforce</goal>
+      </goals>
+      <configuration>
+        <rules>
+          <requirePluginVersions />
+        </rules>
+      </configuration>
+    </execution>
+  </executions>
+</plugin>
+```
+
 ## Building a JAR {#building-a-jar}
 
 Regardless of which strategy is chosen above, the step to build the derivation is the same.
diff --git a/doc/using/overrides.chapter.md b/doc/using/overrides.chapter.md
index 198b4504197d..a1ef9afb0b69 100644
--- a/doc/using/overrides.chapter.md
+++ b/doc/using/overrides.chapter.md
@@ -16,6 +16,12 @@ Example usages:
 pkgs.foo.override { arg1 = val1; arg2 = val2; ... }
 ```
 
+It's also possible to access the previous arguments.
+
+```nix
+pkgs.foo.override (previous: { arg1 = previous.arg1; ... })
+```
+
 <!-- TODO: move below programlisting to a new section about extending and overlays and reference it -->
 
 ```nix
@@ -36,15 +42,15 @@ In the first example, `pkgs.foo` is the result of a function call with some defa
 
 The function `overrideAttrs` allows overriding the attribute set passed to a `stdenv.mkDerivation` call, producing a new derivation based on the original one. This function is available on all derivations produced by the `stdenv.mkDerivation` function, which is most packages in the nixpkgs expression `pkgs`.
 
-Example usage:
+Example usages:
 
 ```nix
-helloWithDebug = pkgs.hello.overrideAttrs (finalAttrs: previousAttrs: {
-  separateDebugInfo = true;
+helloBar = pkgs.hello.overrideAttrs (finalAttrs: previousAttrs: {
+  pname = previousAttrs.pname + "-bar";
 });
 ```
 
-In the above example, the `separateDebugInfo` attribute is overridden to be true, thus building debug info for `helloWithDebug`, while all other attributes will be retained from the original `hello` package.
+In the above example, "-bar" is appended to the pname attribute, while all other attributes will be retained from the original `hello` package.
 
 The argument `previousAttrs` is conventionally used to refer to the attr set originally passed to `stdenv.mkDerivation`.
 
@@ -52,6 +58,16 @@ The argument `finalAttrs` refers to the final attributes passed to `mkDerivation
 
 If only a one-argument function is written, the argument has the meaning of `previousAttrs`.
 
+Function arguments can be omitted entirely if there is no need to access `previousAttrs` or `finalAttrs`.
+
+```nix
+helloWithDebug = pkgs.hello.overrideAttrs {
+  separateDebugInfo = true;
+};
+```
+
+In the above example, the `separateDebugInfo` attribute is overridden to be true, thus building debug info for `helloWithDebug`.
+
 ::: {.note}
 Note that `separateDebugInfo` is processed only by the `stdenv.mkDerivation` function, not the generated, raw Nix derivation. Thus, using `overrideDerivation` will not work in this case, as it overrides only the attributes of the final derivation. It is for this reason that `overrideAttrs` should be preferred in (almost) all cases to `overrideDerivation`, i.e. to allow using `stdenv.mkDerivation` to process input arguments, as well as the fact that it is easier to use (you can use the same attribute names you see in your Nix code, instead of the ones generated (e.g. `buildInputs` vs `nativeBuildInputs`), and it involves less typing).
 :::