schema changes

CHANGELOG.md

@@ -4,9 +4,7 @@ All notable changes to Oragono will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/). For the purposes of versioning, we consider the "public API" to refer to the configuration files, CLI interface and database format.
 
 ## [1.1.0-rc1] - 2019-06-03
-We have a number of exciting improvements in 1.1.0:
+We have a number of exciting improvements in 1.1.0. Highlights include:
-
-Highlights include:
 
 * Support for attaching multiple clients to the same nickname
 * 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
@@ -14,6 +12,8 @@ Highlights include:
 * Support for IP cloaking
 * Simplified commands for registering new accounts with NickServ
 
+This release includes a schema change. If you have `datastore.autoupgrade` set to `true` in your configuration, it will be automatically applied on first restart; otherwise, you can apply it manually as described in the manual.
+
 ### Config changes
 * `tor-listeners` section added, for configuring listeners for use by Tor
 * `compatibility` section added for toggling compatibility behaviors for legacy clients

docs/MANUAL.md

@@ -131,6 +131,20 @@ If you're using Arch, the abovementioned AUR package bundles a systemd file for
 On a non-systemd system, oragono can be configured to log to a file and used [logrotate(8)](https://linux.die.net/man/8/logrotate), since it will reopen its log files (as well as rehashing the config file) upon receiving a SIGHUP.
 
 
+## Upgrading to a new version of Oragono
+
+As long as you are using official releases or release candidates of Oragono, any backwards-incompatible changes should be described in the changelog.
+
+The database has schema versioning; upgrades that involve incompatible changes to the database require schema changes. If you have `datastore.autoupgrade` enabled in your config, any schema changes will be automatically applied the first time you restart your server on the new version. Otherwise, you can apply upgrades manually:
+
+1. Stop your server
+1. Make a backup of your database file
+1. Run `oragono upgradedb` (from the same working directory and with the same arguments that you would use when running `oragono run`)
+1. Start the server again
+
+If you want to run our master branch as opposed to our releases, come find us in #oragono and we can guide you around any potential pitfalls.
+
+
 --------------------------------------------------------------------------------------------