Kill versionchanged:_default versioning

geldata · Feb 15, 2025 · b1121dc · b1121dc
1 parent 6c6e50a
commit b1121dc
Show file tree

Hide file tree

Showing 8 changed files with 95 additions and 199 deletions.
diff --git a/docs/cheatsheets/admin.rst b/docs/cheatsheets/admin.rst
@@ -3,42 +3,39 @@
 Administering an instance
 =========================
 
-.. versionchanged:: _default
+Create a schema branch:
 
-    Create a database:
-
-    .. code-block:: edgeql-repl
-
-        db> create database my_new_project;
-        OK: CREATE DATABASE
-
-.. versionchanged:: 5.0
+.. code-block:: edgeql-repl
 
-    Create a schema branch:
+    db> create schema branch my_new_feature from main;
+    OK: CREATE BRANCH
 
-    .. code-block:: edgeql-repl
 
-        db> create schema branch my_new_feature from main;
-        OK: CREATE BRANCH
+Create a data branch:
 
+.. code-block:: edgeql-repl
 
+    db> create data branch my_new_feature from main;
+    OK: CREATE BRANCH
 
-    Create a data branch:
 
-    .. code-block:: edgeql-repl
+Create an empty branch:
 
-        db> create data branch my_new_feature from main;
-        OK: CREATE BRANCH
+.. code-block:: edgeql-repl
 
+    db> create empty branch my_new_feature;
+    OK: CREATE BRANCH
 
 
-    Create an empty branch:
+.. note::
+    Prior to |Gel| and |EdgeDB| 5.0 *branches* were called *databases*.
+    A command to create a new empty *database* is ``create database``
+    (still supported for backwards compatibility).
 
     .. code-block:: edgeql-repl
 
-        db> create empty branch my_new_feature;
-        OK: CREATE BRANCH
-
+        db> create database my_new_feature;
+        OK: CREATE DATABASE
 
 
 Create a role:

diff --git a/docs/reference/admin/configure.rst b/docs/reference/admin/configure.rst
@@ -8,27 +8,20 @@ Configure
 
 ``configure`` -- change a server configuration parameter
 
-.. versionchanged:: _default
+.. eql:synopsis::
 
-    .. eql:synopsis::
+    configure {session | current branch | instance}
+        set <parameter> := <value> ;
+    configure instance insert <parameter-class> <insert-shape> ;
+    configure {session | current branch | instance} reset <parameter> ;
+    configure {current branch | instance}
+        reset <parameter-class> [ filter <filter-expr> ] ;
 
-        configure {session | current database | instance}
-            set <parameter> := <value> ;
-        configure instance insert <parameter-class> <insert-shape> ;
-        configure {session | current database | instance} reset <parameter> ;
-        configure {current database | instance}
-            reset <parameter-class> [ filter <filter-expr> ] ;
-
-.. versionchanged:: 5.0
-
-    .. eql:synopsis::
-
-        configure {session | current branch | instance}
-            set <parameter> := <value> ;
-        configure instance insert <parameter-class> <insert-shape> ;
-        configure {session | current branch | instance} reset <parameter> ;
-        configure {current branch | instance}
-            reset <parameter-class> [ filter <filter-expr> ] ;
+.. note::
+    Prior to |Gel| and |EdgeDB| 5.0 *branches* were called *databases*.
+    ``configure current branch`` is used to be called
+    ``configure current database``, which is still supported for backwards
+    compatibility.
 
 
 Description
@@ -41,17 +34,9 @@ current session. Some configuration parameters cannot be modified by
 :eql:synopsis:`configure session` and can only be set by
 :eql:synopsis:`configure instance`.
 
-.. versionchanged:: _default
-
-    :eql:synopsis:`configure current database` is used to configure an
-    individual Gel database within a server instance with the
-    changes persisted across server restarts.
-
-.. versionchanged:: 5.0
-
-    :eql:synopsis:`configure current branch` is used to configure an
-    individual Gel branch within a server instance with the
-    changes persisted across server restarts.
+:eql:synopsis:`configure current branch` is used to configure an
+individual Gel branch within a server instance with the
+changes persisted across server restarts.
 
 :eql:synopsis:`configure instance` is used to configure the entire Gel
 instance with the changes persisted across server restarts.  This variant

diff --git a/docs/reference/ddl/migrations.rst b/docs/reference/ddl/migrations.rst
@@ -102,17 +102,9 @@ Create a new migration using an explicit EdgeQL script.
 Parameters
 ----------
 
-.. versionchanged:: _default
-
-    :eql:synopsis:`<edgeql-statement>`
-        Any valid EdgeQL statement, except ``database``, ``role``, ``configure``,
-        ``migration``, or ``transaction`` statements.
-
-.. versionchanged:: 5.0
-
-    :eql:synopsis:`<edgeql-statement>`
-        Any valid EdgeQL statement, except ``database``, ``branch``, ``role``,
-        ``configure``, ``migration``, or ``transaction`` statements.
+:eql:synopsis:`<edgeql-statement>`
+    Any valid EdgeQL statement, except ``database``, ``branch``, ``role``,
+    ``configure``, ``migration``, or ``transaction`` statements.
 
 
 Description

diff --git a/docs/reference/dsn.rst b/docs/reference/dsn.rst
@@ -37,63 +37,37 @@ containing the value (``?host_file=./hostname.txt``).
   For a breakdown of these configuration options, see :ref:`Reference >
   Connection Parameters <ref_reference_connection_granular>`.
 
-.. versionchanged:: _default
-
-    .. list-table::
-
-      * - **Plain param**
-        - **File param**
-        - **Environment param**
-      * - ``host``
-        - ``host_file``
-        - ``host_env``
-      * - ``port``
-        - ``port_file``
-        - ``port_env``
-      * - ``database``
-        - ``database_file``
-        - ``database_env``
-      * - ``user``
-        - ``user_file``
-        - ``user_env``
-      * - ``password``
-        - ``password_file``
-        - ``password_env``
-      * - ``tls_ca_file``
-        - ``tls_ca_file_file``
-        - ``tls_ca_file_env``
-      * - ``tls_security``
-        - ``tls_security_file``
-        - ``tls_security_env``
-
-.. versionchanged:: 5.0
-
-    .. list-table::
-
-      * - **Plain param**
-        - **File param**
-        - **Environment param**
-      * - ``host``
-        - ``host_file``
-        - ``host_env``
-      * - ``port``
-        - ``port_file``
-        - ``port_env``
-      * - ``branch``
-        - ``branch_file``
-        - ``branch_env``
-      * - ``user``
-        - ``user_file``
-        - ``user_env``
-      * - ``password``
-        - ``password_file``
-        - ``password_env``
-      * - ``tls_ca_file``
-        - ``tls_ca_file_file``
-        - ``tls_ca_file_env``
-      * - ``tls_security``
-        - ``tls_security_file``
-        - ``tls_security_env``
+  .. list-table::
+
+    * - **Plain param**
+      - **File param**
+      - **Environment param**
+    * - ``host``
+      - ``host_file``
+      - ``host_env``
+    * - ``port``
+      - ``port_file``
+      - ``port_env``
+    * - ``branch``
+      - ``branch_file``
+      - ``branch_env``
+    * - ``user``
+      - ``user_file``
+      - ``user_env``
+    * - ``password``
+      - ``password_file``
+      - ``password_env``
+    * - ``tls_ca_file``
+      - ``tls_ca_file_file``
+      - ``tls_ca_file_env``
+    * - ``tls_security``
+      - ``tls_security_file``
+      - ``tls_security_env``
+
+.. note::
+    Prior to |Gel| and |EdgeDB| 5.0 *branches* were called *databases*.
+    If you're using or composing a DSN for an older version of |EdgeDB|
+    you should change ``branch*`` options to ``database*``.
 
 **Plain params**
   These "plain" parameters can be used to provide values for options that can't

diff --git a/docs/reference/http.rst b/docs/reference/http.rst
@@ -218,17 +218,9 @@ Making a query request
 
 Make a query to your Gel database using this URL:
 
-.. versionchanged:: _default
-
-    .. code-block::
-
-        http://<hostname>:<port>/db/<database-name>/edgeql
-
-.. versionchanged:: 5.0
-
-    .. code-block::
+.. code-block::
 
-        http://<hostname>:<port>/branch/<branch-name>/edgeql
+    http://<hostname>:<port>/branch/<branch-name>/edgeql
 
 You may make queries via either the POST or GET HTTP method. Query requests can
 take the following fields:

diff --git a/docs/reference/protocol/index.rst b/docs/reference/protocol/index.rst
@@ -45,13 +45,12 @@ HTTP tunnelling differs in a few ways:
 
 *  Authentication is handled at ``/auth/token``.
 
-.. versionchanged:: _default
+*  Query execution is handled at ``/branch/{BRANCH}``.
 
-    *  Query execution is handled at ``/db/{DATABASE}``.
-
-.. versionchanged:: 5.0
-
-    *  Query execution is handled at ``/branch/{BRANCH}``.
+   .. note::
+      Prior to |Gel| and |EdgeDB| 5.0 *branches* were called *databases*.
+      If you're making a request against an older version of |EdgeDB|
+      you should change ``/branch/`` options to ``/db/``.
 
 *  Transactions are not supported.
 
@@ -74,19 +73,12 @@ The auth payload's format is described by the auth method, usually
 ``SCRAM-SHA-256``. If the auth method differs from the requested method,
 the client should abort the authentication attempt.
 
-.. versionchanged:: _default
-
-    Once the :ref:`authentication <ref_authentication>` phase is complete, the
-    final response's body will contain an authorization token used to authenticate
-    the HTTP connection. The client then sends any following message to
-    ``/db/{DATABASE}`` with the following headers:
 
-.. versionchanged:: 5.0
-
-    Once the :ref:`authentication <ref_authentication>` phase is complete, the
-    final response's body will contain an authorization token used to authenticate
-    the HTTP connection. The client then sends any following message to
-    ``/branch/{BRANCH}`` with the following headers:
+Once the :ref:`authentication <ref_authentication>` phase is complete, the
+final response's body will contain an authorization token used to authenticate
+the HTTP connection. The client then sends any following message to
+``/branch/{BRANCH}`` (or ``/db/{DATABASE}`` if you're using a version of
+|EdgeDB| < 5) with the following headers:
 
 * ``X-EdgeDB-User``: The username specified in the
   :ref:`connection parameters <ref_reference_connection>`.
@@ -243,15 +235,8 @@ While it's not required by the protocol specification itself, Gel server
 currently requires setting the following params in
 :ref:`ref_protocol_msg_client_handshake`:
 
-.. versionchanged:: _default
-
-    * ``user`` -- username for authentication
-    * ``database`` -- database to connect to
-
-.. versionchanged:: 5.0
-
-    * ``user`` -- username for authentication
-    * ``branch`` -- branch to connect to
+* ``user`` -- username for authentication
+* ``branch`` -- branch to connect to
 
 
 .. _ref_authentication:
@@ -354,19 +339,10 @@ are always atomic, they will be executed in an implicit transaction block if no
 explicit transaction is currently active. Therefore, EdgeQL scripts have
 limitations on the kinds of EdgeQL commands they can contain:
 
-.. versionchanged:: _default
-
-    * Transaction control commands are not allowed, like ``start transaction``,
-      ``commit``, ``declare savepoint``, or ``rollback to savepoint``.
-    * Non-transactional commands, like ``create database`` or
-      ``configure instance`` are not allowed.
-
-.. versionchanged:: 5.0
-
-    * Transaction control commands are not allowed, like ``start transaction``,
-      ``commit``, ``declare savepoint``, or ``rollback to savepoint``.
-    * Non-transactional commands, like ``create branch`` or
-      ``configure instance`` are not allowed.
+* Transaction control commands are not allowed, like ``start transaction``,
+  ``commit``, ``declare savepoint``, or ``rollback to savepoint``.
+* Non-transactional commands, like ``create branch``,
+  ``configure instance``, or ``create database`` are not allowed.
 
 In the command phase, the server can be in one of the three main states:
 

diff --git a/docs/reference/protocol/typedesc.rst b/docs/reference/protocol/typedesc.rst
@@ -23,23 +23,12 @@ to binary data that Gel can decode and work with.
 A *decoder* is used to decode data from Gel native format to
 data types native to the driver.
 
-.. versionchanged:: _default
-
-    There is one special type with *type id* of zero:
-    ``00000000-0000-0000-0000-000000000000``. The describe result of this type
-    contains zero *blocks*. It's used when a statement returns no meaningful
-    results, e.g. the ``CREATE DATABASE example`` statement.  It is also used
-    to represent the input descriptor when a query does not receive any
-    arguments, or the state descriptor for an empty/default state.
-
-.. versionchanged:: 5.0
-
-    There is one special type with *type id* of zero:
-    ``00000000-0000-0000-0000-000000000000``. The describe result of this type
-    contains zero *blocks*. It's used when a statement returns no meaningful
-    results, e.g. the ``CREATE BRANCH example`` statement.  It is also used to
-    represent the input descriptor when a query does not receive any arguments,
-    or the state descriptor for an empty/default state.
+There is one special type with *type id* of zero:
+``00000000-0000-0000-0000-000000000000``. The describe result of this type
+contains zero *blocks*. It's used when a statement returns no meaningful
+results, e.g. the ``CREATE BRANCH example`` statement.  It is also used to
+represent the input descriptor when a query does not receive any arguments,
+or the state descriptor for an empty/default state.
 
 .. versionadded:: 6.0
 

diff --git a/docs/reference/sdl/index.rst b/docs/reference/sdl/index.rst
@@ -11,19 +11,10 @@ schema.  It is called the Gel *schema definition language* or
 *SDL*.  There's a correspondence between this declarative high-level
 language and the imperative low-level :ref:`DDL <ref_eql_ddl>`.
 
-.. versionchanged:: _default
-
-    SDL is a declarative language optimized for human readability and
-    expressing the state of the Gel schema without getting into the details
-    of how to arrive at that state.  Each *SDL* block represents the complete
-    schema state for a given :ref:`database <ref_datamodel_databases>`.
-
-.. versionchanged:: 5.0
-
-    SDL is a declarative language optimized for human readability and
-    expressing the state of the Gel schema without getting into the details
-    of how to arrive at that state.  Each *SDL* block represents the complete
-    schema state for a given :ref:`branch <ref_datamodel_branches>`.
+SDL is a declarative language optimized for human readability and
+expressing the state of the Gel schema without getting into the details
+of how to arrive at that state.  Each *SDL* block represents the complete
+schema state for a given :ref:`branch <ref_datamodel_branches>`.
 
 Syntactically, an SDL declaration mirrors the ``create`` DDL for the
 corresponding entity, but with all of the ``create`` and ``set``