docs: change project status to stable (#88)

Author: benjie

README.md

@@ -44,22 +44,35 @@ And please give some love to our featured sponsors 🤩:
 
 ## Status
 
-**EXPERIMENTAL**
-
-Tests are in place for many of the APIs, though the API remains undocumented
-(deliberately) and thus if you use the API directly (as opposed to using the
-CLI) you should expect to have to update your code from time to time. (We advise
-using TypeScript to make spotting breaking changes easier.) There are no
-automated integration tests of the CLI yet (although mostly all it does is hand
-off to the API).
-
-There are people (including the maintainer) using this software to manage
-production databases. It is also used in
-[Graphile Starter](https://github.com/graphile/starter). However, it is not for
-the faint of heart - this software is powerful and requires knowledge of SQL. If
-you don't understand what makes Graphile Migrate awesome, or you're concerned
-about it continuing to evolve, you may want to consider an alternative migration
-framework such as these awesome (and quite diverse) projects:
+**STABLE**
+
+This project is intended to be consumed via the CLI, which is stable and is
+being used in production in many projects. The CLI doesn't have explicit tests
+(PR welcome!), but it's a thin wrapper around the programmatic API which has
+copious tests.
+
+The programmatic API is deliberately undocumented; it is not a public interface
+at this time (though it is fully typed in TypeScript). We reserve the right to
+make breaking changes to the programmatic API in patch releases (though this has
+not happened yet and is unlikely to happen without good reason). Should you need
+to use the programmatic API, please get in touch to encourage us to make this a
+supported interface ─ we'd love to know how you're using it!
+
+The project as a whole is stable, but the approach is still "experimental", in
+particular:
+
+- because committed migrations are hashed you cannot edit old migrations; this
+  may cause you issues should you upgrade PostgreSQL and it drops support for a
+  syntax or feature you were previously using. We plan to fix this issue _if and
+  when_ it occurs, so if this affects you please open a detailed issue.
+- the approach of up-only and re-runnable migrations is not for the faint of
+  heart ─ it requires solid SQL knowledge and if insufficient attention is paid
+  it could result in your migrations and your local database state drifting
+  apart (see 'Drift' below).
+
+If you don't understand what makes Graphile Migrate awesome, you may want to
+consider an alternative migration framework such as these awesome (and quite
+diverse) projects:
 
 - [db-migrate](https://db-migrate.readthedocs.io/en/latest/Getting%20Started/commands/)
 - [sqitch](https://sqitch.org/)
@@ -130,13 +143,13 @@ PostgreSQL servers have a default database called `postgres` which is a good
 choice for this).
 
 > Your database URL is needed for most Graphile Migrate commands. The shadow
-> database URL is needed for the development-only commands `commit`, 
-> `uncommit` and `reset`. The root database URL is needed to drop and
-> recreate databases, i.e. for the `reset` command and for commands that call
-> it (`commit` and `uncommit`, which reset the shadow database).
+> database URL is needed for the development-only commands `commit`, `uncommit`
+> and `reset`. The root database URL is needed to drop and recreate databases,
+> i.e. for the `reset` command and for commands that call it (`commit` and
+> `uncommit`, which reset the shadow database).
 >
-> **NOTE**: you should not need the shadow database URL or root database URL
-> in production (you only need the `graphile-migrate migrate` command in
+> **NOTE**: you should not need the shadow database URL or root database URL in
+> production (you only need the `graphile-migrate migrate` command in
 > production) unless you have actions that need them.
 
 ```bash
@@ -730,6 +743,76 @@ Since "superuser" has a specific meaning and is not strictly required for these
 activities we avoid that term, however you may find that you use a superuser as
 your root user - this is expected.
 
+## Drift
+
+> **NOTE**: drift only affects your local development database, it cannot occur
+> in your production database assuming you're only using
+> `graphile-migrate migrate` in production.
+
+In development, if you're insufficiently careful with modifications to
+`current.sql` (including when you choose to save the file, and when switching
+branches in `git`) you may end up with a local database state that differs from
+what you'd expect given the committed migrations and contents of `current.sql`.
+We **strongly recommend against auto-save** for this reason; and recommend that
+you keep a dumped `schema.sql` to help you spot unexpected changes.
+
+Here's an illustrative example to explain the drift phenomenon, with function
+inspired by [XKCD221](https://xkcd.com/221/). Imagine that you're running
+`graphile-migrate watch` locally and you write the following to `current.sql`:
+
+```sql
+-- Revision 1
+create function rnd() returns int as $$
+  select 4;
+$$ language sql stable;
+```
+
+Because `watch` runs the contents of `current.sql` whenever it changes, this
+will create the `rnd()` function in your local database.
+
+A couple seconds later you change your mind, and decide to rename the function,
+writing the following to `current.sql`:
+
+```sql
+-- Revision 2
+create function get_random_number() returns int as $$
+  select 4;
+$$ language sql stable;
+```
+
+This creates `get_random_number()`, but no-one ever said to delete `rnd()`, so
+now both functions exist. According to the committed migrations and
+`current.sql` only `get_random_number()` should exist. The existence of the
+orphaned `rnd()` function in your local database is what we term "drift" ─ this
+function will never appear in your production database even after you commit
+this latest migration; it also won't be in your shadow database (because we
+reset the shadow database and reapply all the migrations frequently).
+
+Since Graphile Migrate doesn't know how to reverse the SQL you've written, it's
+up to you to make the SQL safe so that it can be ran over and over, and adjust
+to your changes. The two to `current.sql` versions above should have been
+
+```sql
+-- Revision 1
+drop function if exists rnd();
+
+create function rnd() returns int as $$
+  select 4;
+$$ language sql stable;
+```
+
+and
+
+```sql
+-- Revision 2
+drop function if exists rnd();
+drop function if exists get_random_number();
+
+create function get_random_number() returns int as $$
+  select 4;
+$$ language sql stable;
+```
+
 ## TODO:
 
 - [ ] Store pgSettings with committed transactions to protect against user edits