book: Migration Guide

book/src/SUMMARY.md

@@ -16,4 +16,5 @@
 - [Configuration](./configuration.md)
 - [Appendix](./appendix.md)
   - [Localisation Guide](./localisation.md)
+  - [Migration Guide (v3 to v4)](./migration.md)
   - [FAQ](./faq.md)

book/src/aur.md

@@ -229,7 +229,7 @@ hotedit = true
 
 ## Updating your AUR Packages
 
-`aura -Au` is the standard command, ran without `sudo`.
+`aura -Au` is the standard command, and is run without `sudo`.
 
 ```
 > aura -Au
@@ -252,7 +252,7 @@ aura :: Proceed? [Y/n]
 ```
 
 The options that apply to normal `-A`, like `-a` and `--hotedit`, also apply
-here. Of course, its simplest to set those in config if you know your
+here. Of course, it's simplest to set those in config if you know your
 preferences. See `man aura` or `aura -Ah` for more options.
 
 ### Displaying PKGBUILD Changes
@@ -418,6 +418,13 @@ This means that when these particular packages are built, it will be done in a
 `chroot`. Transitive AUR dependencies will be injected properly into the build
 environment.
 
+### Using a "build user"
+
+The flags `--build` and `--builduser` can be used to alter where the building
+occurs and under which user it occurs, respectively. While usually not necessary
+by default, these can be useful for system administrators who want stricter
+control.
+
 ### Blindly Accepting all Prompts
 
 Tired of pressing the `Enter` key? Or maybe you've automated `aura` into a

book/src/migration.md

@@ -0,0 +1,77 @@
+# Migration Guide
+
+v4 is a complete overhaul for Aura. Care has been taken to maintain prior usage
+patterns, but there are some changes that the user should be aware of. If you're
+new to Aura, you can skip this entirely and move straight to [Usage](usage.md).
+
+If you notice that something other than what is mentioned here used to work but
+no longer does, please [report it](https://github.com/fosskers/aura/issues).
+
+## sudo
+
+You no longer need to run Aura with `sudo` for "administrative" tasks. So:
+
+```
+> aura -S firefox
+```
+
+"just works", and you'll be prompted for a password as necessary. This is true
+for all Aura commands.
+
+## Package Building
+
+### Build User and Build Directory
+
+Since `sudo` is no longer necessary, Aura runs entirely as your personal user,
+and thus `makepkg` is also invoked internally entirely as you. There are no
+longer any internal user switching hacks just to build packages. This fixes a
+number of historical bugs.
+
+Aura packages were previously built in `/tmp/`, but now they are built in
+`~/.cache/aura/builds/` by default. Aura also keeps its own cache, whereas
+previously all built package tarballs were moved to the pacman cache under
+`/var/`. Doing everything as the local user in the user's own section of the
+filesystem ensures that special permissions are never necessary.
+
+An exception to the above is when `aura` is run as the `root` user, for example
+on remote servers or within Docker containers. In these cases, `root` is
+detected and packages are built under `/tmp/` as the `nobody` user. Since
+`nobody` has no `$HOME` and no permissions to write anywhere else, this helps
+ensure that package building cannot harm your wider system.
+
+### Makepkg output suppression with `-x`
+
+`makepkg` output is now shown by default and cannot be hidden. `-x` is still
+provided to prevent old scripts from breaking, but it has no effect.
+
+### PKGBUILD diff viewing with `-k`
+
+You are now prompted after the diff is printed so that you actually have a
+chance to read what has changed.
+
+### PKGBUILD Analysis
+
+The `-P` command has been removed entirely. Further, automatic analysis that
+occurred before building is now done through `shellcheck`.
+
+## Configuration
+
+Previously Aura was configured in `/etc/aura.conf` using a custom format. Now
+configuration files exist per-user in `~/.config/aura/config.toml` and use the
+TOML format. A fresh configuration file can be generated via:
+
+```
+aura conf --gen > ~/.config/aura/config.toml
+```
+
+### Locale
+
+Aura will auto-detect your system's language from your `$LANG` variable, but
+it's still possible to override this with the `language` field. Previously the
+language code was just the language portion (e.g. `hi`), but now it requires the
+country portion as well (e.g. `hi-IN`, Hindi from India). Acceptable values can
+been found in the output of:
+
+```
+aura stats --lang
+```