Draft 7.x release log (#8945)

This needs to be expanded a bunch, and documentation needs to be
written for some of the new features.

I'm putting this up in part so that it can serve as a TODO list for
docs.

Author: msullivan

docs/resources/changelog/7_x.rst

@@ -0,0 +1,300 @@
+===========
+v7.0 beta 1
+===========
+
+:edb-alt-title: Gel v7
+
+To explore the new features, ensure you specify version 7.0 when initializing
+your project. Pre-release versions are not considered stable and will not be
+automatically suggested:
+
+.. code-block:: bash
+
+  $ gel project init --server-version 7.0-beta.1
+
+
+Upgrading
+=========
+
+.. edb:collapsed::
+
+**Local instances**
+
+To upgrade a local project, first ensure that your CLI is up to date with
+:gelcmd:`cli upgrade`. Then run the following command inside the project
+directory.
+
+.. code-block:: bash
+
+  $ gel project upgrade --to-testing
+
+Alternatively, specify an instance name if you aren't using a project:
+
+.. code-block:: bash
+
+  $ gel instance upgrade -I my_instance
+
+The CLI will check if your schema can migrate cleanly to Gel 7.0. If any
+issues are found, they will be reported.
+
+**Hosted instances**
+
+To upgrade a remote instance, we recommend the following dump-and-restore
+process:
+
+1. Gel v7.0 supports PostgreSQL 14 or above. Verify your PostgreSQL version
+   before upgrading Gel. If you're using Postgres 13 or below, upgrade
+   Postgres first.
+
+2. Spin up an empty 7.0 instance. You can use one of our :ref:`deployment
+   guides <ref_guide_deployment>`.
+
+   For Debian/Ubuntu, when adding the Gel package repository, use this
+   command:
+
+   .. code-block:: bash
+
+       $ echo deb [signed-by=/usr/local/share/keyrings/gel-keyring.gpg] \
+           https://packages.geldata.com/apt \
+           $(grep "VERSION_CODENAME=" /etc/os-release | cut -d= -f2) main \
+           | sudo tee /etc/apt/sources.list.d/gel.list
+       $ sudo apt-get update && sudo apt-get install gel-7
+
+   For CentOS/RHEL, use this installation command:
+
+   .. code-block:: bash
+
+       $ sudo yum install gel-7
+
+   In any required ``systemctl`` commands, replace ``edgedb-server-6`` with
+   ``gel-server-7``.
+
+   For Docker setups, use the ``7.0`` tag.
+
+3. Take your application offline, then dump your v5.x database with the CLI:
+
+   .. code-block:: bash
+
+       $ gel dump --dsn <old dsn> --all --format dir my_database.dump/
+
+   This will dump the schema and contents of your current database to a
+   directory on your local disk called ``my_database.dump``. The directory name
+   isn't important.
+
+4. Restore the empty v6.x instance from the dump:
+
+   .. code-block:: bash
+
+       $ gel restore --all my_database.dump/ --dsn <new dsn>
+
+   Once the restore is complete, update your application to connect to the new
+   instance.
+
+   This process will involve some downtime, specifically during steps 2 and 3.
+
+
+Breaking Changes
+================
+
+SQL adapter access policies on by default
+-----------------------------------------
+
+The default value of ``apply_access_policies_pg`` has been changed
+from ``false`` to ``true``.
+
+This means that by default, EdgeQL access policies will be applied
+when running SQL queries over the SQL protocol connection.
+
+To accomodate third-party tools that cannot be configured to run
+configuration commands, we have introduced the
+``apply_access_policies_pg_default`` field to ``Role`` in order to
+override this:
+
+.. code-block:: edgeql
+
+  CREATE SUPERUSER ROLE pg_connector {
+      # ...
+      SET apply_access_policies_pg_default := false;
+  }
+
+Third-party SQL tools can use the pg_connector role and access
+policies will be disable.
+
+
+Simpler scoping rules deprecation warnings
+------------------------------------------
+
+In 6.0, we began simplifying our scoping rules. See `our RFC 1027 outlining the
+changes
+<https://github.com/geldata/rfcs/blob/master/text/1027-no-factoring.rst>`_.
+
+In 7.0, we emit a warning when creating a migration if the schema does
+not contain ``using simple_scoping;`` or ``using warn_old_scoping;``.
+
+We plan to remove the old scoping in 8.0.
+
+
+New features
+============
+
+Role Based Access Control (RBAC)
+--------------------------------
+
+Gel 7.0 introduces more fine-grained access controls. It is now
+possible to create *non*-SUPERUSER roles, with limited permissions.
+
+Non-SUPERUSER roles deliberately choose the "secure by default" end of
+the security-vs-convenience tradeoff, and are extremely locked down by
+default.
+
+.. code-block:: edgeql
+
+  CREATE ROLE my_role {
+      # ...
+      SET permissions := {
+          sys::perm::data_modifiction,
+          sys::perm::query_stats,
+          cfg::perm::configure_timeouts,
+          cfg::perm::configure_apply_access_policies,
+          ext::auth::perm::auth_read,
+          ext::auth::perm::auth_write,
+      };
+  };
+
+
+Will create a user that can do DDL, look at query stats, configure
+timeouts and whether to use access policies, and read and write the
+auth extension tables.
+
+See `our RFC 1029 for more details on the changes
+<https://github.com/geldata/rfcs/blob/master/text/1029-rbac.rst>`_.
+
+
+* Look up role permissions when executing queries.
+  (:eql:gh:`#8760`)
+
+* Make role permission computation look at all ancestors
+  (:eql:gh:`#8784`)
+
+* Add sys::data_modification to grant non-superusers the ability to run DML.
+  (:eql:gh:`#8771`)
+
+* rbac: Implement RBAC permissions for session configs
+  (:eql:gh:`#8806`)
+
+* rbac: Make the HTTP interfaces aware of the current role
+  (:eql:gh:`#8809`)
+
+* rbac: Support required_permissions for function
+  (:eql:gh:`#8812`)
+
+* rbac: Restrict dump, restore, ADMINISTER, DESCRIBE, ANALYZE
+  (:eql:gh:`#8810`)
+
+* rbac: Make a branch_config permission but require superuser for system
+  (:eql:gh:`#8822`)
+
+* rbac: Make system-wide DDL require SUPERUSER
+  (:eql:gh:`#8823`)
+
+* rbac: Add a branches field to Role to restrict a role to certain branches
+  (:eql:gh:`#8830`)
+
+* rbac: Add sys::perm::superuser which is granted to superusers only.
+  (:eql:gh:`#8853`)
+
+* rbac: Add permissions to stdlib objects and functions.
+  (:eql:gh:`#8846`)
+
+* Add permissions to sys types and functions.
+  (:eql:gh:`#8865`)
+
+* Add ``global sys::current_role``
+  (:eql:gh:`#8889`)
+
+
+Other features
+--------------
+
+* Support required link properties
+  (:eql:gh:`#8735`)
+
+* Allow (most) unparenthesized statements in calls, etc
+  (:eql:gh:`#8763`)
+
+* Implement sys::approximate_count()
+  (:eql:gh:`#8692`)
+
+* Implement ``splat_strategy`` qualifier for pointers
+  (:eql:gh:`#8757`)
+
+* Add http schedule_request with json body.
+  (:eql:gh:`#8724`)
+
+* Support graphql over the binary protocol
+  (:eql:gh:`#8878`)
+
+* One-time code implementation for ``ext::auth``
+  (:eql:gh:`#8905`)
+
+
+
+Additional changes
+==================
+
+
+Fixes
+-----
+
+
+* Fix schema type inconsistencies with collection aliases
+  (:eql:gh:`#8672`)
+
+* Fix mangled type names leaking into introspectable names
+  (:eql:gh:`#8772`)
+
+* Drop bionic support
+  (:eql:gh:`#8328`)
+
+* Check that function parameter and return types exist when migrating.
+  (:eql:gh:`#8386`)
+
+* Add hint to partial path errors if anchor is available.
+  (:eql:gh:`#8380`)
+
+* Implement permissions in access policies over SQL adapter
+  (:eql:gh:`#8837`)
+
+* Support creating indexes concurrently
+  (:eql:gh:`#8747`)
+
+* Fix WITH computation duplication in auth module
+  (:eql:gh:`#8851`)
+
+* Access policies for link tables over SQL adapter
+  (:eql:gh:`#8849`)
+
+* Fix params with union types producing ISEs
+  (:eql:gh:`#8863`)
+
+* Support intersection and complex composite types in SDL parameters.
+  (:eql:gh:`#8864`)
+
+* Add ``std::identifier`` annotations to abstract operators
+  (:eql:gh:`#8862`)
+
+
+Other
+-----
+
+* Warn on START MIGRATION if no scoping future is present
+  (:eql:gh:`#8896`)
+
+* Add ``apply_access_policies_pg_default`` flag to ``Role``
+  (:eql:gh:`#8918`)
+
+* Expose 'protected' on schema::Property
+  (:eql:gh:`#8930`)
+
+* Retry serialization errors that occur internal to the auth extension.
+  (:eql:gh:`#8942`)

docs/resources/changelog/index.rst

@@ -15,4 +15,5 @@ Changes introduced in all of the releases of |Gel| so far:
     4_x
     5_x
     6_x
+    7_x
     deprecation