From 7ed4f284cea788af404045c754bee0da39746ca8 Mon Sep 17 00:00:00 2001 From: Albin Coquereau Date: Thu, 14 Sep 2023 08:16:39 +0200 Subject: [PATCH] doc: add a breaking change file with documentation for the renaming of attestation --- docs/index.rst | 1 + docs/introduction/breaking_changes.rst | 76 ++++++++++++++++++++++++++ 2 files changed, 77 insertions(+) create mode 100644 docs/introduction/breaking_changes.rst diff --git a/docs/index.rst b/docs/index.rst index bfa806f04cbb..f8839f84b373 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -148,6 +148,7 @@ Platform developers are also provided reference materials for internal APIs of O introduction/test_networks introduction/get_troubleshooting introduction/support + BREAKING CHANGES .. toctree:: :maxdepth: 2 diff --git a/docs/introduction/breaking_changes.rst b/docs/introduction/breaking_changes.rst new file mode 100644 index 000000000000..98cc208cf064 --- /dev/null +++ b/docs/introduction/breaking_changes.rst @@ -0,0 +1,76 @@ +Breaking changes +================ + +This section presents the breaking changes that users can encounter between +different Protocols or Octez versions. It complements the "Breaking changes" +sections in the development changelogs by providing more context and/or less +fragmented mentions. + +For each change, there may be a subsection ``deprecation`` and ``breaking +changes``. The first subsection will explain what changes can be made during a +deprecation phase to adapt smoothly to the new changes. The second subsection +will present the changes that can not be done by the deprecation mechanism and +that may be breaking. + +Attestations +------------ + +Starting from the protocol :doc:`Oxford <../protocols/018_oxford>` and the Octez +``v18`` the legacy attestation name ``endorsement`` is now deprecated and +``attestation`` should be used everywhere. Then, ``preendorsement`` is renamed +to ``preattestation``, ``double_preendorsement_evidence`` to +``double_preattestation_evidence``, and ``double_endorsement_evidence`` to +``double_attestation_evidence``. The same goes for operation receipts such as +``lost endorsing rewards``, which are renamed to ``lost attesting rewards``. + +To allow a smooth transition we implemented a deprecation mechanism that will +start with Oxford and Octez ``v18`` and should end in two protocols and two +Octez releases. We were not able to version everything so some changes, detailed +below, are breaking. + +Deprecation +~~~~~~~~~~~ + +For the Oxford and Octez ``v18`` we introduced a new :doc:`version argument +<../user/versioning>` ``?version=`` for the following RPCs that can output +``attestation`` (and legacy ``endorsement``): + +* ``POST /chains//blocks//helpers/scripts/run_operation`` +* ``POST /chains//blocks//helpers/scripts/simulate_operation`` +* ``POST /chains//blocks//helpers/preapply/operations`` +* ``POST /chains//blocks//helpers/parse/operations`` +* ``GET /chains//blocks/`` +* ``GET /chains//blocks//operations`` +* ``GET /chains//blocks//operations/`` +* ``GET /chains//blocks//operations//`` +* ``GET /chains//blocks//metadata`` +* ``GET /chains//mempool/monitor_operations`` +* ``GET /chains//mempool/pending_operations`` + +See :doc:`changelog<../CHANGES>` for more details. + +For protocol ``O`` and version ``v18``, using the version ``0``, which is the +default value, will still output the legacy attestation name. Version ``1`` +allows the RPCs to output ``attestation`` instead of the legacy name. + +For a protocol upgrade proposal to succeed Oxford, i.e. for protocol ``P``, and +the next major release of Octez, v19.0, the default value of these RPCs will be +``1`` but the version ``0`` will still be usable. + +Version ``0`` and support for legacy name ("endorsement") will be removed in the +subsequent protocol and major Octez versions -- that is, protocol upgrade +proposal ``Q`` and Octez v20.0 + +As an exception, for the ``GET /chains//mempool/pending_operations`` RPC, +in protocol ``O`` and version ``v18``, due to previous versioning of this RPC, +the legacy version is already ``1`` (currently the default) and you should use +version ``2`` to output ``attestation``. + +Breaking changes +~~~~~~~~~~~~~~~~ + +Starting with protocol :doc:`Oxford <../protocols/018_oxford>`, the protocol +parameters, storage fields and errors that were using the legacy attestation +name now use ``attestation``. The baker and accuser will no longer use the +legacy attestation name in their event messages and errors and will use +``attestation`` instead. -- GitLab