butane/docs: add file append and overwrite examples

butane/docs/examples.md

@@ -149,6 +149,53 @@ storage:
       mode: 0644
 ```
 
+Use ordinary `contents` when Butane should write the complete contents of a file. With the default `overwrite: false` this creates a new file, and Ignition fails if a file already exists at the path; set `overwrite: true` to replace an existing one. Use `append` with the safe default `overwrite: false` when the existing contents should be preserved and one or more fragments added to the end. This example adds a sudoers rule to the end of the shipped `/etc/sudoers`. The rule deliberately allows only one command with exact arguments; avoid granting unrestricted passwordless access to shells, package managers, or container runtimes, since that is equivalent to root access.
+
+<!-- butane-config -->
+```yaml
+variant: fcos
+version: 1.7.0
+storage:
+  files:
+    - path: /etc/sudoers
+      overwrite: false
+      append:
+        - inline: |
+            core ALL=(ALL) NOPASSWD: /usr/bin/systemctl restart example.service
+```
+
+For sudoers rules specifically, a drop-in under `/etc/sudoers.d/` is usually preferable to appending to `/etc/sudoers`, since it survives updates to the shipped file. The same `append` semantics apply, and a new drop-in needs an explicit `mode`:
+
+<!-- butane-config -->
+```yaml
+variant: fcos
+version: 1.7.0
+storage:
+  files:
+    - path: /etc/sudoers.d/core
+      mode: 0440
+      overwrite: false
+      append:
+        - inline: |
+            core ALL=(ALL) NOPASSWD: /usr/bin/systemctl restart example.service
+```
+
+Use `overwrite: true` with `contents` when any existing filesystem node at the path should be removed and replaced. This example replaces anything at `/etc/example.conf` with a regular file containing the specified settings.
+
+<!-- butane-config -->
+```yaml
+variant: fcos
+version: 1.7.0
+storage:
+  files:
+    - path: /etc/example.conf
+      overwrite: true
+      contents:
+        inline: |
+          enabled = true
+      mode: 0644
+```
+
 ### Directory trees
 
 Consider a directory tree at `~/conf/tree` on the system running Butane:

docs/release-notes.md

@@ -16,6 +16,7 @@ nav_order: 9
 - Refactored the Makefile and build script to match the Fedora RPM spec: separate build targets per binary, with `VERSION` and linker flags passed in at build time
 - `build_blackbox_tests` builds a blackbox-specific `ignition` binary with `make`
 - CI and GitHub Actions updated to build via `make ignition` and `make ignition-validate`
+- Document file `append` and `overwrite` behavior with examples ([#2270](https://github.com/coreos/ignition/issues/2270))
 
 ### Bug fixes