diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e3a18c6e7eb40..092480e62ce1c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -14,7 +14,7 @@ under the terms of [COPYING](COPYING), which is an MIT-like license.
 * Format the commit messages in the following way:
 
   ```
-  (pkg-name | nixos/<module>): (from -> to | init at version | refactor | etc)
+  ((<pkg-name> | treewide) | nixos/(<module> | treewide)): (from -> to | init at version | refactor | etc)
 
   (Motivation for change. Additional information.)
   ```
@@ -28,6 +28,8 @@ under the terms of [COPYING](COPYING), which is an MIT-like license.
   * nixos/hydra: add bazBaz option
 
     Dual baz behavior is needed to do foo.
+  * nixos/treewide: escape pkgs reference in examples and descriptions
+  * treewide: gnome2.gtk -> gtk2
   * nixos/nginx: refactor config generation
 
     The old config generation system used impure shell scripts and could break in specific circumstances (see #1234).
@@ -42,6 +44,10 @@ under the terms of [COPYING](COPYING), which is an MIT-like license.
 
 See the nixpkgs manual for more details on [standard meta-attributes](https://nixos.org/nixpkgs/manual/#sec-standard-meta-attributes) and on how to [submit changes to nixpkgs](https://nixos.org/nixpkgs/manual/#chap-submitting-changes).
 
+### Treewide changes
+
+Changes that affect a large portion of the tree should be prefixed with `treewide:` or `nixos/treewide`.
+
 ## Writing good commit messages
 
 In addition to writing properly formatted commit messages, it's important to include relevant information so other developers can later understand *why* a change was made. While this information usually can be found by digging code, mailing list/Discourse archives, pull request discussions or upstream changes, it may require a lot of work.
diff --git a/doc/contributing/submitting-changes.chapter.md b/doc/contributing/submitting-changes.chapter.md
index 221ba3006194a..4d34eb7ee024f 100644
--- a/doc/contributing/submitting-changes.chapter.md
+++ b/doc/contributing/submitting-changes.chapter.md
@@ -28,7 +28,7 @@
 - Format the commit in a following way:
 
   ```
-  (pkg-name | nixos/<module>): (from -> to | init at version | refactor | etc)
+  ((<pkg-name> | treewide) | nixos/(<module> | treewide)): (from -> to | init at version | refactor | etc)
   Additional information.
   ```
 
@@ -36,6 +36,8 @@
     - `nginx: init at 2.0.1`
     - `firefox: 54.0.1 -> 55.0`
     - `nixos/hydra: add bazBaz option`
+    - `nixos/treewide: escape pkgs reference in examples and descriptions`
+    - `treewide: gnome2.gtk -> gtk2`
     - `nixos/nginx: refactor config generation`
 
 - Test your changes. If you work with