manual and changelog updates for #563

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).

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