Propuestas de mejora en Conflux

tonyycc · 9 November 2021 21:29

Las propuestas de mejora en Conflux (CIPs en inglés) describen los estándares en la plataforma de Conflux, incluyendo las específicaciones del protocolo principal, clientes de las APIs, y estándares de los contratos.

¿Cómo contribuir?

Revisa el CIP-1
Clona el repositorio dando click en “fork” en la esquina superior derecha.
Añade tu CIP en tu repositorio clonado. Al final de este publicado se encuentra una plantilla para los CIP.
Envia un Pull Request a el repositorio para los CIPs de Conflux.

Tu primer PR debe ser un primer borrador del CIP final. Debes cumplir con los criterios de formato exigidos por la compilación (en gran medida, metadatos correctos en el encabezado). Un editor revisará manualmente el primer PR para un nuevo CIP y te asignará un número antes de fusionarlo. Asegúrate de incluir un encabezado de discusión con la URL de un foro de discusión o abrir un issue de GitHub donde los usuarios puedan discutir el CIP.

Si tu CIP requiere imágenes, los archivos de imagen deben incluirse en un subdirectorio de la carpeta de activos para ese CIP de la siguiente manera: assets/CIP-N (donde N se debe reemplazar con el número CIP). Al vincular a una imagen en el CIP, utiliza vínculos relativos como …/assets/CIP-1/image.png.

Una vez que se fusione tu primer PR, tenemos un bot que ayuda a fusionar automáticamente los PR para redactar los CIP. Para que esto funcione, debes poder decir que eres el propietario del borrador que se está editando. Asegúrate de que la línea “author” de tu CIP contenga tu nombre de usuario de GitHub o tu dirección de correo electrónico. Si usas tu dirección de correo electrónico, esa dirección debe ser la que se muestra públicamente en tu perfil de GitHub.

Cuando creas que tu CIP está en una etapa madura y lista para avanzar de la fase de borrador, deberas solicitar que se agende una próxima reunión con los desarrolladores principales, donde se discute su inclusión en una bifurcación futura. Si los implementadores aceptan incluirlo, los editores del CIP actualizarán el estado de tu CIP a Accepted.

Términos del Estado de un CIP

Draft: un CIP que está experimentando cambios e iteraciones rápidas.
Last Call: un CIP que se realiza con su iteración inicial y está listo para ser revisado por una amplia audiencia.

· Accepted: un CIP que ha estado en Last Call durante al menos 2 semanas y el autor ha abordado los cambios técnicos solicitados. El proceso para que los desarrolladores principales decidan si codificar un CIP en sus clientes como parte de un hard fork no es parte del proceso CIP. Si se toma tal decisión, el CIP pasará a Final.

· Final: un CIP que los desarrolladores principales han decidido implementar y lanzar en un futuro hard fork o que ya se ha lanzado en un hard fork.

¿Qué es un CIP?

CIP son las siglas de Conflux Improvement Proposal (propuesta de mejora de Conflux). Un CIP es un documento de diseño que proporciona información a la comunidad de Conflux o describe una nueva característica de Conflux o sus procesos o entorno. El CIP debe proporcionar una especificación técnica concisa de la función y una justificación para la función.

Pretendemos que los CIP sean los mecanismos principales para proponer nuevas funciones, para recopilar las opiniones de la comunidad sobre un tema y para documentar las decisiones de diseño que se han incluido en Conflux. El autor del CIP es responsable de generar consenso dentro de la comunidad y de documentar las opiniones generales. Debido a que los CIP se mantienen como archivos de texto en un repositorio versionado, su historial de revisión es el registro histórico de la propuesta de función.

Para los implementadores de Conflux, los CIP son una forma conveniente de realizar un seguimiento del progreso de su implementación. Idealmente, los encargados de la implementación deberían enumerar los CIP que han implementado. Esto brindará a los usuarios finales una forma conveniente de conocer el estado actual de una implementación o biblioteca determinada.

Tipos de CIP

Existen 4 tipos de CIP.

Cambios compatibles con versiones anteriores: el cliente actualizado bajo este CIP será totalmente compatible con versiones anteriores. Dichos cambios pueden introducir API de RPC adicionales u otras características nuevas. Para enviar un cambio compatible con versiones anteriores, sigue este proceso:

Clona el repositorio conflux-rust y envía una solicitud de fusión (PR).
Si se trata de un cambio complicado, envía un problema para comunicarte primero con el equipo principal de desarrolladores.

Cambios importantes en la base de datos / RPC: el cliente actualizado podrá coexistir con versiones anteriores, pero actualiza la interfaz / comportamiento de un RPC existente o cambia el formato de la base de datos de la blockchain. Esto requeriría modificaciones para las aplicaciones que dependen de estos RPC y / o limpiar la base de datos para sincronizar desde cero. Para enviar un cambio importante en la base de datos / RPC, puedes seguir el proceso anterior, pero primero debes enviar un issue en GitHub.

Cambios que modifican el protocolo: estos cambios no afectan la especificación del Protocolo Conflux, pero requieren una actualización del protocolo de red P2P en Conflux / Conflux-Rust. Es posible habilitar el cambio sin una bifurcación, pero requeriría un manejo especial de la versión del protocolo y pruebas de compatibilidad. Para enviar un cambio que modifique el protocolo, sigue este proceso:

Envía un borrador de propuesta de mejora de Conflux (CIP).
Discute el CIP hasta que sea aceptado. Ten en cuenta que en el CIP, es importante especificar cómo la implementación puede mantener la compatibilidad con versiones anteriores del protocolo (mediante control de versiones u otras técnicas). Si esto no se puede hacer, el cambio debe clasificarse y tratarse como un cambio que rompe las especificaciones.
Crea un issue en Conflux-Rust correspondiente al CIP.
Envía una solicitud de fusión (PR) que implemente el CIP en GitHub.
Auditar, probar y / o verificar la implementación. El RP se fusionará con la rama principal (master). El equipo principal de desarrolladores puede optar por fusionar también el PR con otras ramas para las versiones de los clientes de Conflux-Rust.
Una vez que una versión habilita el cambio, actualiza el estado de CIP a Final.

Cambios que modifican las especificaciones: estos cambios requieren una actualización de la especificación del protocolo Conflux. Requeriría una bifurcación dura para permitir el cambio. No tiene ninguna compatibilidad con versiones anteriores. El proceso general para realizar cambios de modificación en las especificaciones es el siguiente:

Envía un borrador de propuesta de mejora de Conflux (CIP). El borrador debe discutir cómo habilitar este cambio en una bifurcación dura.
Discute el CIP hasta que sea aceptado.
Crea un issue en el repositorio Conflux-Protocol correspondiente al CIP.
Envía una solicitud de fusión (PR) al repositorio Conflux-Protocol para cambiar la especificación de acuerdo con el CIP.
Crea un issue en el repositorio de Conflux-Rust correspondiente al CIP.

· Envía una solicitud de fusión (PR) implementando el CIP.

· Auditar, probar y / o verificar la implementación. El PR se fusionará con la rama principal (master).

· Espera una bifurcación para permitir el cambio. Cambia el estado de CIP a Final.

NOTA: Actualmente, los modos de cliente ligero en Conflux-Rust se consideran experimentales. Todos los cambios que solo afecten a los clientes ligeros se considerarán compatibles con versiones anteriores por ahora.

Se recomienda que un único CIP contenga una única propuesta clave o una nueva idea. Cuanto más enfocado está el CIP, más exitoso tiende a ser. Un cambio en un cliente no requiere un CIP; un cambio que afecta a varios clientes, o define un estándar para el uso de varias aplicaciones, sí lo hace.

Un CIP exitoso debe cumplir con ciertos criterios mínimos. Debe ser una descripción clara y completa de la mejora propuesta. La mejora debe representar una mejora neta. La implementación propuesta, en su caso, debe ser sólida y no debe complicar indebidamente el protocolo.

Si un CIP menciona o propone cambios a la Máquina Virtual, debe consultar las instrucciones por sus mnemónicos y definir los códigos de operación de esos mnemónicos al menos una vez. Una forma preferida es la siguiente:

· REVERT (0xfe)

Flujo de trabajo en un CIP

El manejo en un CIP

Las partes involucradas en el proceso eres tu, el autor del CIP, los editores del CIP y los desarrolladores principales de Conflux.

Antes de comenzar a escribir un CIP formal, debes examinar tu idea. Pregunta primero a la comunidad de Conflux si una idea es original para evitar perder el tiempo en algo que será rechazado en base a investigaciones previas. Por lo tanto, se recomienda abrir un hilo de discusión en la sección issues de este repositorio.

Además de asegurarte de que tu idea sea original, será tu papel como autor dejar tu idea clara a los revisores y las partes interesadas, así como invitar a los editores, desarrolladores y la comunidad a dar su opinión sobre los canales antes mencionados. Debe intentar evaluar si el interés en su CIP es acorde con el trabajo involucrado en su implementación y cuántas partes tendrán que cumplir con él. Por ejemplo, el trabajo requerido para implementar un CIP que modifica las especificaciones será mucho mayor que para un CIP compatible con versiones anteriores y el CIP necesitará suficiente interés por parte del equipo del cliente de Conflux. Los comentarios negativos de la comunidad se tomarán en consideración y pueden evitar que su CIP pase de la etapa de Borrador.

Dado que los CIP requieren que las implementaciones de los clientes se consideren definitivas (consulta el “Proceso de los CIP” a continuación), deberás proporcionar una implementación para los clientes o convencer a los clientes de que implementen tu CIP.

En resumen, tu papel como autor es redactar el CIP utilizando el estilo y formato que se describen a continuación, guiar las discusiones en los foros apropiados y generar consenso en la comunidad en torno a la idea.

Proceso del CIP

A continuación se muestra el proceso por el que avanzará un CIP exitoso:

· [IDEA] -> [DRADT] -> [LAST CALL] -> [ACCEPTED] -> [FINAL]

Cada cambio de estado es solicitado por el autor del CIP y revisado por los editores del CIP. Utiliza una solicitud de fusión (PR) para actualizar el estado. Incluye un enlace al lugar donde las personas deben continuar discutiendo tu CIP. Los editores del CIP procesarán estas solicitudes según las condiciones a continuación.

Idea: una vez que el editor ha preguntado a la comunidad de Conflux si una idea tiene alguna posibilidad de apoyo, redactarán un borrador de CIP como una solicitud de fusión (PR). Considera incluir una implementación si esto ayudará a las personas a estudiar el CIP.

Draft - Si estás de acuerdo, el editor del CIP asignará al CIP un número (generalmente el número de issue o PR relacionado con el CIP) y fusionará tu solicitud de fusión (PR). El editor del CIP no negará injustificadamente un CIP.
Draft - Las razones para denegar el estado de borrador incluyen ser demasiado desenfocado, demasiado amplio, duplicar esfuerzos, ser técnicamente incorrecto, no proporcionar la motivación adecuada o abordar la compatibilidad con versiones anteriores, o no seguir la filosofía de Conflux.
Borrador: una vez que se ha fusionado el primer borrador, puedes enviar solicitudes de extracción de seguimiento con cambios adicionales en tu borrador hasta el momento en que creas que el CIP está en una etapa madura y listo para pasar al siguiente estado.
Last Call: si estás de acuerdo, el editor de CIP asignará el estado de Last Call y establecerá una fecha de finalización de la revisión (revisión-período-fin), normalmente 14 días después.
Last Call: se rechazará una solicitud de estado de Last Call si aún se espera que se realicen cambios materiales en el borrador. Esperamos que los CIP solo ingresen a Last Call una vez.
Last Call: este CIP aparecerá en un lugar destacado en el sitio web.
- Un CIP en estado Last Call que resulte en cambios importantes o quejas técnicas no resueltas hará que el CIP vuelva al borrador.
Accepted: se aceptará un CIP en estado Last Call exitoso sin cambios materiales o quejas técnicas no resueltas.
Accepted: este estado indica que los cambios son poco probables y los desarrolladores de clientes de Conflux deben considerar este CIP para su inclusión. Su proceso para decidir si codificarlo en sus clientes como parte de un hard fork no es parte del proceso CIP.
Draft: los desarrolladores principales pueden decidir mover este CIP al estado de Draft a su discreción. P.ej. Se encontró una falla importante, pero corregible, en el CIP.
Rejected: los desarrolladores centrales pueden decidir marcar este CIP como Rechazado a su discreción. P.ej. En el CIP se encontró una falla importante, pero incorregible.
Final - Los CIP deben implementarse antes de que puedan considerarse finales. Cuando la implementación esté completa y adoptada por la comunidad, el estado cambiará a “Final”.
Final: este CIP representa el estado actual de la técnica. Un CIP final solo debe actualizarse para corregir pequeños detalles.

Otros estados excepcionales incluyen:

Active: algunos CIP también pueden tener un estado de “Active” si nunca se pretende que se completen. P.ej. CIP-1 (este CIP).
Abandoned: los autores originales ya no persiguen este CIP o puede que ya no sea una opción (técnicamente) preferida.
Draft: los autores que deseen seguir este CIP pueden solicitar que se cambie al estado de Draft.
Rejected: un CIP que es fundamentalmente roto o rechazado por los desarrolladores centrales y no se implementará. Un CIP no puede salir de este estado.
Superseded: un CIP que anteriormente era Final pero que ya no se considera de última generación. Otro CIP estará en estado Final y hará referencia al CIP Reemplazado. Un CIP no puede salir de este estado.

¿Qué características tiene un CIP exitoso?

Cada CIP debe tener las siguientes partes:

Preámbulo: encabezados de estilo RFC 822 que contienen metadatos sobre el CIP, incluido el número CIP, un título descriptivo breve (limitado a un máximo de 44 caracteres) y los detalles del autor. Consulta los detalles a continuación.
Resumen: una descripción breve (~ 200 palabras) del problema técnico que se está abordando.
Motivación (*opcional): la motivación es fundamental para los CIP que desean cambiar el protocolo Conflux. Debes explicar claramente por qué la especificación del protocolo existente es inadecuada para abordar el problema que resuelve el CIP. Las presentaciones del CIP sin motivación suficiente pueden rechazarse muy pronto.
Especificación: la especificación técnica debe describir la sintaxis y la semántica de cualquier característica nueva. La especificación debe ser lo suficientemente detallada para permitir implementaciones competidoras e interoperables para cualquiera de las plataformas Conflux actuales (conflux-rust).
Justificación: la justificación completa la especificación al describir qué motivó el diseño y por qué se tomaron decisiones de diseño particulares. Debes describir los diseños alternativos que se consideraron y el trabajo relacionado, p. Ej. cómo se admite la función en otros lenguajes. La justificación también puede proporcionar evidencia de consenso dentro de la comunidad y debe discutir las objeciones o preocupaciones importantes que surjan durante la discusión.
Compatibilidad con versiones anteriores: todos los CIP que introducen incompatibilidades con versiones anteriores deben incluir una sección que describa estas incompatibilidades y su gravedad. El CIP debe explicar cómo se propone el autor abordar estas incompatibilidades. Las presentaciones del CIP sin un tratado de retrocompatibilidad suficiente pueden ser rechazadas muy pronto.
Casos de prueba: los casos de prueba para una implementación son obligatorios para los CIP que están afectando los cambios de consenso. Otros CIP pueden optar por incluir enlaces a casos de prueba, si corresponde.
Implementaciones: las implementaciones deben completarse antes de que cualquier CIP reciba el estado “Final”, pero no es necesario que se complete antes de que el CIP se fusione como draft. Si bien hay mérito en el enfoque de llegar a un consenso sobre la especificación y la justificación antes de escribir el código, el principio de “consenso aproximado y código en ejecución” sigue siendo útil cuando se trata de resolver muchas discusiones sobre los detalles de la API.
Consideraciones de seguridad: todos los CIP deben contener una sección que discuta las implicaciones / consideraciones de seguridad relevantes para el cambio propuesto. Incluye información que pueda ser importante para las discusiones de seguridad, que exponga los riesgos y que se pueda utilizar durante todo el ciclo de vida de la propuesta. P.ej. Incluye decisiones de diseño relevantes para la seguridad, preocupaciones, discusiones importantes, guías específicas de implementación y trampas, un resumen de amenazas y riesgos y cómo se están abordando. Las presentaciones de CIP que no incluyan la sección “Consideraciones de seguridad” serán rechazadas. Un CIP no puede pasar al estado “Final” sin una discusión de Consideraciones de seguridad considerada suficiente por los revisores.
Exención de derechos de autor: todos los CIP deben ser de dominio público. Consulta la parte inferior de este CIP para ver un ejemplo de exención de derechos de autor.

Formatos y plantillas CIP

Los CIP deben escribirse en formato de markdown. Los archivos de imagen deben incluirse en un subdirectorio de la carpeta de assets para ese CIP de la siguiente manera:

assets/cip-N (donde N debe reemplazarse con el número CIP).

Al vincular a una imagen en el CIP, utiliza vínculos relativos como …/assets/cip-1/image.png.

Preámbulo del encabezado CIP

Cada CIP debe comenzar con un preámbulo de encabezado estilo RFC 822, precedido y seguido de tres guiones (-). Jekyll también denomina este encabezado “material preliminar”. Los encabezados deben aparecer en el siguiente orden. Los encabezados marcados con “*” son opcionales y se describen a continuación. Todos los demás encabezados son obligatorios.

cip: número CIP (lo determina el editor CIP)

title: título del CIP

author: una lista del (los) autor (es) nombre (s) y / o nombre de usuario (s), o nombre (s) y correo electrónico (s). Los detalles se encuentran a continuación.

*discussions-to: una URL que apunta al hilo de discusión oficial.

*review-period-end: fecha en que finaliza el período de revisión

type: Backward Compatible | Database/RPC Breaking | Protocol Breaking | Spec Breaking

created: fecha de creación

*updated: lista de fechas separadas por comas

*requires: número (s) de CIP (s) requerido (s)

*replaces: número (s) de CIP (s) remplazado (s)

*superseded-by: número (s) de CIP (s) remplazado (s)

*resolution: una URL que apunta a la resolución de este CIP

Los encabezados que permiten listas deben separar los elementos con comas.

Los encabezados que requieren fechas siempre lo harán en el formato de ISO 8601 (aaaa-mm-dd).

encabezado del autor

El encabezado del autor enumera opcionalmente los nombres, direcciones de correo electrónico o nombres de usuario de los autores / propietarios del CIP. Aquellos que prefieren el anonimato pueden usar solo un nombre de usuario, o un nombre y un nombre de usuario. El formato del valor del encabezado del autor debe ser:

Aleatorio J. Dirección de [email protected]

o

Usuario J. aleatorio (@nombredeusuario)

si se incluye la dirección de correo electrónico o el nombre de usuario de GitHub, y

Usuario J. aleatorio

si no se proporciona la dirección de correo electrónico.

encabezado de resolución

El encabezado de resolución contiene una URL que debe apuntar a un mensaje de correo electrónico u otro recurso web donde se realiza el pronunciamiento sobre el CIP.

encabezado de discusiones

Si bien un CIP es un borrador, un encabezado de discusión indicará la lista de correo o URL donde se está discutiendo el CIP. No es necesario un encabezado de discusión si el CIP se está discutiendo en privado con el autor.

Como única excepción, las discusiones no pueden apuntar a solicitudes de fusión (PR) de GitHub.

tipo de encabezado

El encabezado de tipo especifica el tipo de CIP: compatible con versiones anteriores, ruptura de base de datos / RPC, ruptura de protocolo, ruptura de especificaciones.

encabezado creado

El encabezado creado registra la fecha en la que se asignó un número al CIP. Ambos encabezados deben estar en formato aaaa-mm-dd, p. Ej. 2001-08-14.

encabezado actualizado

El encabezado actualizado registra la (s) fecha (s) en que se actualizó el CIP con cambios “sustanciales”. Este encabezado solo es válido para los CIP de estado Draft y Active.

encabezado de requisitos

Los CIP pueden tener un encabezado de requisitos, que indica los números de CIP de los que depende este CIP.

reemplazado por y reemplaza los encabezados

Los CIP también pueden tener un encabezado reemplazado por que indica que un CIP ha quedado obsoleto por un documento posterior; el valor es el número del CIP que reemplaza al documento actual. El CIP más nuevo debe tener un encabezado de reemplazo que contenga el número del CIP que dejó obsoleto.

Archivos auxiliares

Los CIP pueden incluir archivos auxiliares como diagramas. Dichos archivos deben llamarse CIP-N-Y.ext, donde N es el número CIP, Y es un número de serie (que comienza en 1) y “ext” se reemplaza por la extensión del archivo real (por ejemplo, “png”).

Transferencia de la propiedad de CIP

En ocasiones, es necesario transferir la propiedad de un CIP a un nuevo author. En general, nos gustaría retener al autor original como coautor del CIP transferido, pero eso realmente depende del autor original. Una buena razón para transferir la propiedad es porque el autor original ya no tiene el tiempo o el interés en actualizarlo o seguir adelante con el proceso CIP, o ha caído de la red (es decir, es inalcanzable o no responde al correo electrónico ). Una mala razón para transferir la propiedad es que no está de acuerdo con las instrucciones del CIP. Intentamos crear consenso en torno a un CIP, pero si eso no es posible, siempre puede enviar un CIP competidor.

Si estás interesado en asumir la propiedad de un CIP, envía un mensaje solicitando hacerse cargo, dirigido tanto al autor original como al editor del CIP. Si el autor original no responde al correo electrónico de manera oportuna, el editor del CIP tomará una decisión unilateral (no es que tales decisiones no puedan revertirse :)).

Responsabilidades del editor de CIP

Para cada nuevo CIP que ingresa, un editor hace lo siguiente:

Leer el CIP para comprobar si está listo: sólido y completo. Las ideas deben tener sentido técnico, incluso si no parece probable que lleguen al estado final.
El título debe describir con precisión el contenido.
Verificar el CIP en busca de lenguaje (ortografía, gramática, estructura de oraciones, etc.), marcado (Markdown con sabor a GitHub), estilo de código
Si el CIP no está listo, el editor se lo enviará al autor para que lo revise, con instrucciones específicas.

Una vez que el CIP esté listo para el repositorio, el editor de CIP:

Asigna un número CIP (generalmente el número del PR o, si lo prefiere el autor, el número del issue si hubo una discusión en la sección de problemas de este repositorio sobre este CIP)

Aceptar la solicitud de fusión (PR) correspondiente

Envíar un mensaje al autor del CIP con el siguiente paso.

Los editores de CIP monitorean los cambios de CIP y corrigen cualquier error de estructura, gramática, ortografía o marcado que veamos.

Los editores no emiten juicios sobre los CIP. Simplemente hacemos la parte administrativa y editorial.