From 29b1dd37a86db5f7c24779ac790979a6e6e42a39 Mon Sep 17 00:00:00 2001
From: Shivaram Lingamneni <slingamn@cs.stanford.edu>
Date: Thu, 20 Jun 2019 00:24:42 -0400
Subject: [PATCH] manual and changelog updates for #563

---
 CHANGELOG.md   | 10 +++++++---
 docs/MANUAL.md |  3 +++
 2 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4eefbc1d..b6269e1a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,16 +10,20 @@ We're pleased to be publishing the release candidate for 1.1.0 (the official rel
 * Support for the newly ratified [message tags](https://ircv3.net/specs/extensions/message-tags.html) and [message ID](https://ircv3.net/specs/extensions/message-ids.html) IRCv3 specifications; client developers are invited to use Oragono as a reference when implementing these specifications.
 * Support for running Oragono as a Tor hidden service.
 
+### Upgrade notes
+
 This release includes a database change. If you have `datastore.autoupgrade` set to `true` in your configuration, it will be automatically applied when you restart Oragono; otherwise, you can update the database manually by running `oragono upgradedb`.
 
+No changes to your configuration file should be required for this upgrade; however, updating the file is necessary to enable some new functionality, as described below.
+
 ### Config changes
 * `tor-listeners` section added for configuring listeners for use with Tor.
 * `compatibility` section added for toggling compatibility behaviors for legacy clients.
 * `ip-cloaking` section added for configuring cloaking.
 * `bouncer` section added for configuring bouncer-like features (in particular, whether multiple clients can use the same nickname).
-* `check-ident` now defaults to `false`.
-* `nick-reservation.method` now defaults to `"strict"`.
-* `fakelag.enabled` now defaults to `true`
+* `check-ident` now has recommended value `false`.
+* `nick-reservation.method` now has recommended value "strict"`.
+* `fakelag.enabled` now has recommended value `true`.
 * `limits.linelen.tags` removed due to ratification of the [message-tags spec](https://ircv3.net/specs/extensions/message-tags.html), which fixes the maximum tags length at 8191 bytes.
 * `limits.registration-messages` added to restrict how many messages a user can send to the server during connection registration (while connecting to the server).
 * `channels.operator-only-creation` added to optionally restrict creation of new channels to ircops (#537).
diff --git a/docs/MANUAL.md b/docs/MANUAL.md
index 7dd564f4..bdfdf45d 100644
--- a/docs/MANUAL.md
+++ b/docs/MANUAL.md
@@ -22,6 +22,7 @@ _Copyright © Daniel Oaks <daniel@danieloaks.net>, Shivaram Lingamneni <slingamn
 - Installing
     - Windows
     - macOS / Linux / Raspberry Pi
+    - Upgrading
 - Features
     - User Accounts
         - Nickname reservation
@@ -135,6 +136,8 @@ On a non-systemd system, oragono can be configured to log to a file and used [lo
 
 As long as you are using official releases or release candidates of Oragono, any backwards-incompatible changes should be described in the changelog.
 
+In general, the config file format should be fully backwards and forwards compatible. Unless otherwise noted, no config file changes should be necessary when upgrading Oragono. However, the "config changes" section of the changelog will typically describe new sections that can be added to your config to enable new functionality, as well as changes in the recommended values of certain fields.
+
 The database is versioned; upgrades that involve incompatible changes to the database require updating the database. If you have `datastore.autoupgrade` enabled in your config, the database will be backed up and upgraded when you restart your server when required. Otherwise, you can apply upgrades manually:
 
 1. Stop your server