From d73aa6c87c1685f8ce1c9e1068ec12048927b2b7 Mon Sep 17 00:00:00 2001 From: Josh Thomas Date: Mon, 23 Oct 2023 14:52:30 -0500 Subject: [PATCH] add notes on updating to README (#53) * add notes on updating to README * tweaks --- README.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a79c227..b1fbeda 100644 --- a/README.md +++ b/README.md @@ -186,7 +186,23 @@ See the documentation [here](#configuration) for general information about confi ## Updating -TODO +As `django-email-relay` involves database models and the potential for migrations, care should be taken when updating to ensure that all Django projects using `django-email-relay` are upgraded at roughly the same time. See the [deprecation policy](#deprecation-policy) for more information regarding backwards incompatible changes. + +When updating to a new version, it is recommended to follow the following steps: + +1. Update the relay service to the new version. As part of the update process, the relay service should run any migrations that are needed. If using the provided Docker container, this is done automatically as Django's `migrate` command is baked into the image. When running the relay service from a Django project, you will need to run the `migrate` command yourself, either as part of your deployment strategy or manually. +2. Update all distributed projects to the new version. + +### Deprecation Policy + +Any changes that involve models and/or migrations, or anything else that is potentially backwards incompatible, will be split across two or more releases: + +1. A release that adds the changes in a backwards compatible way, with a deprecation warning. This release will be tagged with a minor version bump, e.g. `0.1.0` to `0.2.0`. +2. A release that removes the backwards compatible changes and removes the deprecation warning. This release will be tagged with a major version bump, e.g. `0.2.0` to `1.0.0`. + +This is unlikely to happen often, but it is important to keep in mind when updating. + +A major release does not necessarily mean that there are breaking changes or ones involving models and migrations. You should always check the [changelog](CHANGELOG.md) and a version's release notes for more information. ## Usage