From cedaac14982cd3f229469dbf00799b6e2d728b5d Mon Sep 17 00:00:00 2001 From: Meaghan FitzGerald Date: Tue, 30 Jul 2024 17:35:20 -0400 Subject: [PATCH 1/2] Update CODEOWNERS Signed-off-by: Meaghan FitzGerald --- .github/CODEOWNERS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 06bfd14be43..bd960d45b6a 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1 +1 @@ -* @laviniat1996 @dubrado @meaghanfitzgerald @martineckardt @Andyvargtz @ashucoder9 @usmaneth @amandamarquis1 +* @laviniat1996 @meaghanfitzgerald @martineckardt @Andyvargtz @ashucoder9 @usmaneth @amandamarquis1 From 87d4db6b6fb12e24e9478e9cec97089d9cbe401a Mon Sep 17 00:00:00 2001 From: Meaghan FitzGerald Date: Wed, 31 Jul 2024 13:35:56 -0400 Subject: [PATCH 2/2] Fix build errors, add hardcoded ACP explainer (#1803) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * acp removed from imports * remoteContent.js * acp doc no longer imported to docs * sourceBaseUrl corrections, indentation corrections * the * vale * 馃挰Generate LLM translations * spanish --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .github/styles/Vocab/Products/accept.txt | 2 + .gitignore | 1 - configs/remoteContent.js | 119 +++++++----------- docs/learn/acp.md | 114 +++++++++++++++++ .../current/learn/acp.md | 104 +++++++++++++++ 5 files changed, 263 insertions(+), 77 deletions(-) create mode 100644 docs/learn/acp.md create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/learn/acp.md diff --git a/.github/styles/Vocab/Products/accept.txt b/.github/styles/Vocab/Products/accept.txt index d8738c39289..cfe27dfba96 100644 --- a/.github/styles/Vocab/Products/accept.txt +++ b/.github/styles/Vocab/Products/accept.txt @@ -16,6 +16,7 @@ alloc Alloc alloweds ANR's +ANCs Ansible API's apis @@ -150,6 +151,7 @@ infeasibly Infura inlined ints +interoperate IPCs ipfs IPFS diff --git a/.gitignore b/.gitignore index f255ea802ae..b5a1cb70b5c 100644 --- a/.gitignore +++ b/.gitignore @@ -17,7 +17,6 @@ docs/build/cross-chain/teleporter/upgradeability.md docs/build/cross-chain/teleporter/cli.md docs/build/cross-chain/awm/evm-integration.md docs/build/cross-chain/awm/relayer.md -docs/learn/acp.md # AvalancheGo API from GH repo via docusaurus-plugin-remote-content docs/reference/avalanchego/p-chain/api.md diff --git a/configs/remoteContent.js b/configs/remoteContent.js index dc01101e1cb..c6778dd9314 100644 --- a/configs/remoteContent.js +++ b/configs/remoteContent.js @@ -99,13 +99,13 @@ const remoteContent = [ return { filename: "deep-dive.md", content: `--- -tags: [Avalanche Warp Messaging, AWM, Cross-Subnet Communication, Cross-Chain Communication] -description: Avalanche Warp Messaging (AWM) provides a primitive for cross-subnet communication on the Avalanche Network. -keywords: [ docs, documentation, avalanche, awm, cross-subnet communication, cross-chain, cross-chain communication ] -sidebar_label: Deep Dive -sidebar_position: 1 + tags: [Avalanche Warp Messaging, AWM, Cross-Subnet Communication, Cross-Chain Communication] + description: Avalanche Warp Messaging (AWM) provides a primitive for cross-subnet communication on the Avalanche Network. + keywords: [ docs, documentation, avalanche, awm, cross-subnet communication, cross-chain, cross-chain communication ] + sidebar_label: Deep Dive + sidebar_position: 1 --- - + ${updatedContent}`, }; } @@ -138,11 +138,11 @@ ${updatedContent}`, return { filename: "relayer.md", content: `--- -tags: [Avalanche Warp Messaging, Relayer] -description: Reference relayer implementation for cross-chain Avalanche Warp Message delivery. -keywords: [ docs, documentation, avalanche, teleporter, awm, cross-subnet communication, cross-chain, cross-chain communication ] -sidebar_label: Run a Relayer -sidebar_position: 3 + tags: [Avalanche Warp Messaging, Relayer] + description: Reference relayer implementation for cross-chain Avalanche Warp Message delivery. + keywords: [ docs, documentation, avalanche, teleporter, awm, cross-subnet communication, cross-chain, cross-chain communication ] + sidebar_label: Run a Relayer + sidebar_position: 3 --- ${newContent}`, @@ -158,7 +158,7 @@ ${newContent}`, // /docs/build/cross-chain/teleporter/overview.md name: "teleporter-overview", sourceBaseUrl: - "https://raw.githubusercontent.com/ava-labs/teleporter/main/contracts/src/Teleporter/", + "https://raw.githubusercontent.com/ava-labs/teleporter/main/contracts/src/teleporter/", documents: ["README.md"], outDir: "docs/build/cross-chain/teleporter/", // change file name and add metadata correct links @@ -166,7 +166,7 @@ ${newContent}`, if (filename.includes("README")) { const updatedContent = replaceRelativeLinks( content, - "https://github.com/ava-labs/teleporter/blob/main/contracts/src/Teleporter/" + "https://github.com/ava-labs/teleporter/blob/main/contracts/src/teleporter/" ); const newContent = insertLinesAfterFirstLine( @@ -177,11 +177,11 @@ ${newContent}`, return { filename: "overview.md", content: `--- -tags: [Teleporter, Cross-Subnet Communication, Cross-Chain Communication] -description: Teleporter is a messaging protocol built on top of Avalanche Warp Messaging that provides a developer-friendly interface for sending and receiving cross-chain messages from within the EVM. -keywords: [ docs, documentation, avalanche, teleporter, awm, cross-subnet communication, cross-chain, cross-chain communication ] -sidebar_label: Overview -sidebar_position: 1 + tags: [Teleporter, Cross-Subnet Communication, Cross-Chain Communication] + description: Teleporter is a messaging protocol built on top of Avalanche Warp Messaging that provides a developer-friendly interface for sending and receiving cross-chain messages from within the EVM. + keywords: [ docs, documentation, avalanche, teleporter, awm, cross-subnet communication, cross-chain, cross-chain communication ] + sidebar_label: Overview + sidebar_position: 1 --- ${newContent}`, @@ -211,12 +211,12 @@ ${newContent}`, return { filename: "deep-dive.md", content: `--- -tags: [Teleporter, Cross-Subnet Communication, Cross-Chain Communication] -description: Teleporter is an EVM compatible cross-subnet communication protocol built on top of Avalanche Warp Messaging (AWM), and implemented as a Solidity smart contract. It provides a mechanism to asynchronously invoke smart contract functions on other EVM blockchains within Avalanche. Teleporter provides a handful of useful features on top of AWM, such as specifying relayer incentives for message delivery, replay protection, message delivery and execution retries, and a standard interface for sending and receiving messages within a dApp deployed across multiple subnets. -keywords: [ docs, documentation, avalanche, teleporter, awm, cross-subnet communication, cross-chain, cross-chain communication ] -sidebar_label: Deep Dive -sidebar_position: 2 -title: Teleporter Deep Dive + tags: [Teleporter, Cross-Subnet Communication, Cross-Chain Communication] + description: Teleporter is an EVM compatible cross-subnet communication protocol built on top of Avalanche Warp Messaging (AWM), and implemented as a Solidity smart contract. It provides a mechanism to asynchronously invoke smart contract functions on other EVM blockchains within Avalanche. Teleporter provides a handful of useful features on top of AWM, such as specifying relayer incentives for message delivery, replay protection, message delivery and execution retries, and a standard interface for sending and receiving messages within a dApp deployed across multiple subnets. + keywords: [ docs, documentation, avalanche, teleporter, awm, cross-subnet communication, cross-chain, cross-chain communication ] + sidebar_label: Deep Dive + sidebar_position: 2 + title: Teleporter Deep Dive --- ${updatedContent}`, @@ -251,11 +251,11 @@ ${updatedContent}`, return { filename: "cli.md", content: `--- -tags: [Teleporter, Cross-Subnet Communication, Cross-Chain Communication] -description: This page the source code for the Avalanche Teleporter CLI. The CLI is a command line interface for interacting with the Teleporter contracts. It is written with [cobra](https://github.com/spf13/cobra) commands as a Go application. -keywords: [ docs, documentation, avalanche, teleporter, awm, cross-subnet communication, cross-chain, cross-chain communication, teleporter cli ] -sidebar_label: CLI -sidebar_position: 6 + tags: [Teleporter, Cross-Subnet Communication, Cross-Chain Communication] + description: This page the source code for the Avalanche Teleporter CLI. The CLI is a command line interface for interacting with the Teleporter contracts. It is written with [cobra](https://github.com/spf13/cobra) commands as a Go application. + keywords: [ docs, documentation, avalanche, teleporter, awm, cross-subnet communication, cross-chain, cross-chain communication, teleporter cli ] + sidebar_label: CLI + sidebar_position: 6 --- ${newContent}`, @@ -271,7 +271,7 @@ ${newContent}`, // /docs/build/cross-chain/teleporter/upgradeability.md name: "teleporter-upgradeability", sourceBaseUrl: - "https://raw.githubusercontent.com/ava-labs/teleporter/main/contracts/src/Teleporter/upgrades/", + "https://raw.githubusercontent.com/ava-labs/teleporter/main/contracts/src/teleporter/registry/", documents: ["README.md"], outDir: "docs/build/cross-chain/teleporter/", // change file name and add metadata correct links @@ -279,7 +279,7 @@ ${newContent}`, if (filename.includes("README")) { const updatedContent = replaceRelativeLinks( content, - "https://github.com/ava-labs/teleporter/blob/main/contracts/src/Teleporter/upgrades/" + "https://github.com/ava-labs/teleporter/blob/main/contracts/src/teleporter/registry/" ); const newContent = insertLinesAfterFirstLine( @@ -290,11 +290,11 @@ ${newContent}`, return { filename: "upgradeability.md", content: `--- -tags: [Teleporter, Cross-Subnet Communication, Cross-Chain Communication] -description: Teleporter is an EVM-compatible cross-subnet communication protocol built on top of Avalanche Warp Messaging. The TeleporterMessenger contract is non-upgradable, once a version of the contract is deployed it cannot be changed. However, there could still be new versions of TeleporterMessenger contracts needed to be deployed in the future. -keywords: [ docs, documentation, avalanche, teleporter, awm, cross-subnet communication, cross-chain, cross-chain communication ] -sidebar_label: Upgradeability -sidebar_position: 5 + tags: [Teleporter, Cross-Subnet Communication, Cross-Chain Communication] + description: Teleporter is an EVM-compatible cross-subnet communication protocol built on top of Avalanche Warp Messaging. The TeleporterMessenger contract is non-upgradable, once a version of the contract is deployed it cannot be changed. However, there could still be new versions of TeleporterMessenger contracts needed to be deployed in the future. + keywords: [ docs, documentation, avalanche, teleporter, awm, cross-subnet communication, cross-chain, cross-chain communication ] + sidebar_label: Upgradeability + sidebar_position: 5 --- ${newContent}`, @@ -310,10 +310,10 @@ ${newContent}`, // /docs/build/cross-chain/teleporter/evm-integration.md name: "awm-evm-integration", sourceBaseUrl: - "https://raw.githubusercontent.com/meaghanfitzgerald/coreth/docs-integration/precompile/contracts/warp/", + "https://raw.githubusercontent.com/ava-labs/coreth/master/precompile/contracts/warp/", documents: ["README.md"], outDir: "docs/build/cross-chain/awm/", - // change file name and add metadata correct links + // change the file name and add metadata correct links modifyContent(filename, content) { if (filename.includes("README")) { const updatedContent = replaceRelativeLinks( @@ -323,44 +323,11 @@ ${newContent}`, return { filename: "evm-integration.md", content: `--- -tags: [Avalanche Warp Messaging, Coreth, Subnet-EVM, Cross-Subnet Communication, Cross-Chain Communication] -description: Avalanche Warp Messaging provides a basic primitive for signing and verifying messages between Subnets. The receiving network can verify whether an aggregation of signatures from a set of source Subnet validators represents a threshold of stake large enough for the receiving network to process the message. The Avalanche Warp Precompile enables this flow to send a message from blockchain A to blockchain B. -keywords: [ coreth, subnet-evm, docs, documentation, avalanche, teleporter, awm, cross-subnet communication, cross-chain, cross-chain communication ] -sidebar_label: EVM Integration -sidebar_position: 2 ---- - -${updatedContent}`, - }; - } - return undefined; - }, - }, - ], - [ - "docusaurus-plugin-remote-content", - { - // /docs/learn/acp.md - name: "acp-overview", - sourceBaseUrl: - "https://raw.githubusercontent.com/meaghanfitzgerald/ACPs/main/", - documents: ["README.md"], - outDir: "docs/learn/", - // change file name and add metadata, correct links - modifyContent(filename, content) { - if (filename.includes("README")) { - const updatedContent = replaceRelativeLinks( - content, - "https://github.com/avalanche-foundation/ACPs/blob/main/" - ); - return { - filename: "acp.md", - content: `--- -tags: [Avalanche Community Proposals, ACPs] -description: An Avalanche Community Proposal is a concise document that introduces a change or best practice for adoption on the Avalanche Network. ACPs should provide clear technical specifications of any proposals and a compelling rationale for their adoption. ACPs are an open framework for proposing improvements and gathering consensus around changes to the Avalanche Network. ACPs can be proposed by anyone. -keywords: [ avalanche, nodes, preference, avalanche improvements, open source, acps, avalanche community proposals ] -sidebar_label: Avalanche Community Proposals -sidebar_position: 0 + tags: [Avalanche Warp Messaging, Coreth, Subnet-EVM, Cross-Subnet Communication, Cross-Chain Communication] + description: Avalanche Warp Messaging provides a basic primitive for signing and verifying messages between Subnets. The receiving network can verify whether an aggregation of signatures from a set of source Subnet validators represents a threshold of stake large enough for the receiving network to process the message. The Avalanche Warp Precompile enables this flow to send a message from blockchain A to blockchain B. + keywords: [ coreth, subnet-evm, docs, documentation, avalanche, teleporter, awm, cross-subnet communication, cross-chain, cross-chain communication ] + sidebar_label: EVM Integration + sidebar_position: 2 --- ${updatedContent}`, diff --git a/docs/learn/acp.md b/docs/learn/acp.md new file mode 100644 index 00000000000..22300d1ba85 --- /dev/null +++ b/docs/learn/acp.md @@ -0,0 +1,114 @@ +--- +tags: [Avalanche Community Proposals, ACPs] +description: An Avalanche Community Proposal is a concise document that introduces a change or best practice for adoption on the Avalanche Network. ACPs should provide clear technical specifications of any proposals and a compelling rationale for their adoption. ACPs are an open framework for proposing improvements and gathering consensus around changes to the Avalanche Network. ACPs can be proposed by anyone. +keywords: + [ + avalanche, + nodes, + preference, + avalanche improvements, + open source, + acps, + avalanche community proposals, + ] +sidebar_label: Avalanche Community Proposals +sidebar_position: 0 +--- + +# What is an Avalanche Community Proposal (ACP)? + +[](https://github.com/avalanche-foundation/ACPs) + +An Avalanche Community Proposal is a concise document that introduces a change or best practice for adoption on the [Avalanche Network](https://www.avax.com). ACPs should provide clear technical specifications of any proposals and a compelling rationale for their adoption. + +ACPs are an open framework for proposing improvements and gathering consensus around changes to the Avalanche Network. ACPs can be proposed by anyone and will be merged into this repository as long as they are well-formatted and coherent. Once an overwhelming majority of the Avalanche Network/Community have [signaled their support for an ACP](https://docs.avax.network/nodes/configure/avalanchego-config-flags#avalanche-community-proposals), it may be scheduled for activation on the Avalanche Network by Avalanche Network Clients (ANCs). It is ultimately up to members of the Avalanche Network/Community to adopt ACPs they support by running a compatible ANC, such as [AvalancheGo](https://github.com/ava-labs/avalanchego). + +## ACP Tracks + +There are three kinds of ACP: + +- A `Standards Track` ACP describes a change to the design or function of the Avalanche Network, such as a change to the P2P networking protocol, P-Chain design, Subnet architecture, or any change/addition that affects the interoperability of Avalanche Network Clients (ANCs). +- A `Best Practices Track` ACP describes a design pattern or common interface that should be used across the Avalanche Network to make it easier to integrate with Avalanche or for Subnets to interoperate with each other. This would include things like proposing a smart contract interface, not proposing a change to how smart contracts are executed. +- A `Meta Track` ACP describes a change to the ACP process or suggests a new way for the Avalanche Community to collaborate. +- A `Subnet Track` ACP describes a change to a particular Subnet. This would include things like configuration changes or coordinated Subnet upgrades. + +## ACP Statuses + +There are four statuses of an ACP: + +- A `Proposed` ACP has been merged into the main branch of the ACP repository. It is actively being discussed by the Avalanche Community and may be modified based on feedback. +- An `Implementable` ACP is considered "ready for implementation" by the author and will no longer change meaningfully from its current form (which would require a new ACP). +- An `Activated` ACP has been activated on the Avalanche Network via a coordinated upgrade by the Avalanche Community. Once an ACP is `Activated`, it is locked. +- A `Stale` ACP has been abandoned by its author because it is not supported by the Avalanche Community or has been replaced with another ACP. + +## ACP Workflow + +### Step 0: Think of a Novel Improvement to Avalanche + +The ACP process begins with a new idea for Avalanche. Each potential ACP must have an author: someone who writes the ACP using the style and format described below, shepherds the associated GitHub Discussion, and attempts to build consensus around the idea. Note that ideas and any resulting ACP is public. Authors should not post any ideas or anything in an ACP that the Author wants to keep confidential or to keep ownership rights in (such as intellectual property rights). + +### Step 1: Post Your Idea to [GitHub Discussions](https://github.com/avalanche-foundation/ACPs/discussions/categories/ideas) + +The author should first attempt to ascertain whether there is support for their idea by posting in the "Ideas" category of GitHub Discussions. Vetting an idea publicly before going as far as writing an ACP is meant to save both the potential author and the wider Avalanche Community time. Asking the Avalanche Community first if an idea is original helps prevent too much time being spent on something that is guaranteed to be rejected based on prior discussions (searching the Internet does not always do the trick). It also helps to make sure the idea is applicable to the entire community and not just the author. Small enhancements or patches often don't need standardization between multiple projects; these don't need an ACP and should be injected into the relevant development workflow with a patch submission to the applicable ANC issue tracker. + +### Step 2: Propose an ACP via [Pull Request](https://github.com/avalanche-foundation/ACPs/pulls) + +Once the author feels confident that an idea has a decent chance of acceptance, an ACP should be drafted and submitted as a pull request (PR). This draft must be written in ACP style as described below. It is highly recommended that a single ACP contain a single key proposal or new idea. The more focused the ACP, the more successful it tends to be. If in doubt, split your ACP into several well-focused ones. The PR number of the ACP will become its assigned number. + +### Step 3: Build Consensus on [GitHub Discussions](https://github.com/avalanche-foundation/ACPs/discussions/categories/discussion) and Provide an Implementation (if Applicable) + +ACPs will be merged by ACP maintainers if the proposal is generally well-formatted and coherent. ACP editors will attempt to merge anything worthy of discussion, regardless of feasibility or complexity, that is not a duplicate or incomplete. After an ACP is merged, an official GitHub Discussion will be opened for the ACP and linked to the proposal for community discussion. It is recommended for author or supportive Avalanche Community members to post an accompanying non-technical overview of their ACP for general consumption in this GitHub Discussion. The ACP should be reviewed and broadly supported before a reference implementation is started, again to avoid wasting the author and the Avalanche Community's time, unless a reference implementation will aid people in studying the ACP. + +### Step 4: Mark ACP as `Implementable` via [Pull Request](https://github.com/avalanche-foundation/ACPs/pulls) + +Once an ACP is considered complete by the author, it should be marked as `Implementable`. At this point, all open questions should be addressed and an associated reference implementation should be provided (if applicable). As mentioned earlier, the Avalanche Foundation meets periodically to recommend the ratification of specific ACPs but it is ultimately up to members of the Avalanche Network/Community to adopt ACPs they support by running a compatible Avalanche Network Client (ANC), such as [AvalancheGo](https://github.com/ava-labs/avalanchego). + +### [Optional] Step 5: Mark ACP as `Stale` via [Pull Request](https://github.com/avalanche-foundation/ACPs/pulls) + +An ACP can be superseded by a different ACP, rendering the original obsolete. If this occurs, the original ACP will be marked as `Stale`. ACPs may also be marked as `Stale` if the author abandon work on it for a prolonged period of time (12+ months). ACPs may be reopened and moved back to `Proposed` if the author restart work. + +## What Belongs in a Successful ACP? + +Each ACP must have the following parts: + +- `Preamble`: Markdown table containing metadata about the ACP, including the ACP number, a short descriptive title, the author, and optionally the contact info for each author, etc. +- `Abstract`: Concise (~200 word) description of the ACP +- `Motivation`: Rationale for adopting the ACP and the specific issue/challenge/opportunity it addresses +- `Specification`: Complete description of the semantics of any change should allow any ANC/Avalanche Community member to implement the ACP +- `Security Considerations`: Security implications of the proposed ACP + +Each ACP can have the following parts: + +- `Open Questions`: Questions that should be resolved before implementation + +Each `Standards Track` ACP must have the following parts: + +- `Backwards Compatibility`: List of backwards incompatible changes required to implement the ACP and their impact on the Avalanche Community +- `Reference Implementation`: Code, documentation, and telemetry (from a local network) of the ACP change + +Each `Best Practices Track` ACP can have the following parts: + +- `Backwards Compatibility`: List of backwards incompatible changes required to implement the ACP and their impact on the Avalanche Community +- `Reference Implementation`: Code, documentation, and telemetry (from a local network) of the ACP change + +### ACP Formats and Templates + +Each ACP is allocated a unique subdirectory in the `ACPs` directory. The name of this subdirectory must be of the form `N-T` where `N` is the ACP number and `T` is the ACP title with any spaces replaced by hyphens. ACPs must be written in [markdown](https://daringfireball.net/projects/markdown/syntax) format and stored at `ACPs/N-T/README.md`. Please see the [ACP template](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/TEMPLATE.md) for an example of the correct layout. + +### Auxiliary Files + +ACPs may include auxiliary files such as diagrams or code snippets. Such files should be stored in the ACP's subdirectory (`ACPs/N-T/*`). There is no required naming convention for auxiliary files. + +### Waived Copyright + +ACP authors must waive any copyright claims before an ACP will be merged into the repository. This can be done by including the following text in an ACP: + +```text +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). +``` + +## Contributing + +Before contributing to ACPs, please read the [ACP Terms of Contribution](https://github.com/avalanche-foundation/ACPs/blob/main/CONTRIBUTING.md). diff --git a/i18n/es/docusaurus-plugin-content-docs/current/learn/acp.md b/i18n/es/docusaurus-plugin-content-docs/current/learn/acp.md new file mode 100644 index 00000000000..1e355ad448c --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/learn/acp.md @@ -0,0 +1,104 @@ +--- +tags: [Propuestas de la Comunidad Avalanche, ACPs] +description: Una Propuesta de la Comunidad Avalanche es un documento conciso que introduce un cambio o una mejor pr谩ctica para su adopci贸n en la Red Avalanche. Las ACPs deben proporcionar especificaciones t茅cnicas claras de cualquier propuesta y una justificaci贸n convincente para su adopci贸n. Las ACPs son un marco abierto para proponer mejoras y reunir consenso en torno a los cambios en la Red Avalanche. Cualquier persona puede proponer ACPs. +keywords: + [ + avalanche, + nodos, + preferencia, + mejoras avalanche, + c贸digo abierto, + acps, + propuestas de la comunidad avalanche, + ] +sidebar_label: Propuestas de la Comunidad Avalanche +sidebar_position: 0 +--- + +# 驴Qu茅 es una Propuesta de la Comunidad Avalanche (ACP)? + +[](https://github.com/avalanche-foundation/ACPs) + +Una Propuesta de la Comunidad Avalanche es un documento conciso que introduce un cambio o una mejor pr谩ctica para su adopci贸n en la [Avalanche Network](https://www.avax.com). Las ACPs deben proporcionar especificaciones t茅cnicas claras de cualquier propuesta y una justificaci贸n convincente para su adopci贸n. + +Las ACPs son un marco abierto para proponer mejoras y reunir consenso en torno a los cambios en la Red Avalanche. Cualquier persona puede proponer ACPs y se fusionar谩n en este repositorio siempre que est茅n bien formateadas y sean coherentes. Una vez que una abrumadora mayor铆a de la Red/Comunidad Avalanche ha [se帽alado su apoyo a una ACP](https://docs.avax.network/nodes/configure/avalanchego-config-flags#avalanche-community-proposals), puede programarse su activaci贸n en la Red Avalanche por parte de los Clientes de la Red Avalanche (ANCs). En 煤ltima instancia, depende de los miembros de la Red/Comunidad Avalanche adoptar las ACPs que apoyan ejecutando un ANC compatible, como [AvalancheGo](https://github.com/ava-labs/avalanchego). + +## Pistas de ACP + +Hay tres tipos de ACP: + +- Una ACP de `Pista de Est谩ndares` describe un cambio en el dise帽o o la funci贸n de la Red Avalanche, como un cambio en el protocolo de red P2P, el dise帽o de la Cadena-P, la arquitectura de las Subredes, o cualquier cambio/adici贸n que afecte a la interoperabilidad de los Clientes de la Red Avalanche (ANCs). +- Una ACP de `Pista de Mejores Pr谩cticas` describe un patr贸n de dise帽o o una interfaz com煤n que se debe utilizar en toda la Red Avalanche para facilitar la integraci贸n con Avalanche o para que las Subredes interoperen entre s铆. Esto incluir铆a cosas como proponer una interfaz de contrato inteligente, no proponer un cambio en c贸mo se ejecutan los contratos inteligentes. +- Una ACP de `Pista Meta` describe un cambio en el proceso de las ACPs o sugiere una nueva forma para que la Comunidad Avalanche colabore. +- Una ACP de `Pista de Subred` describe un cambio en una Subred en particular. Esto incluir铆a cosas como cambios de configuraci贸n o actualizaciones coordinadas de la Subred. + +## Estados de las ACPs + +Hay cuatro estados de una ACP: + +- Una ACP `Propuesta` se ha fusionado en la rama principal del repositorio de ACPs. Se est谩 discutiendo activamente por la Comunidad Avalanche y puede modificarse en funci贸n de los comentarios. +- Una ACP `Implementable` se considera "lista para su implementaci贸n" por parte del autor y ya no cambiar谩 significativamente en + +El autor debe primero intentar determinar si hay apoyo para su idea publicando en la categor铆a "Ideas" de las Discusiones de GitHub. Vetar una idea p煤blicamente antes de llegar tan lejos como escribir un ACP tiene como objetivo ahorrar tiempo tanto al autor potencial como a la comunidad Avalanche en general. Preguntar primero a la comunidad Avalanche si una idea es original ayuda a evitar que se gaste demasiado tiempo en algo que est谩 garantizado a ser rechazado basado en discusiones previas (buscar en Internet no siempre funciona). Tambi茅n ayuda a asegurar que la idea sea aplicable a toda la comunidad y no solo al autor. Peque帽as mejoras o parches a menudo no necesitan estandarizaci贸n entre m煤ltiples proyectos; estos no necesitan un ACP y deben ser inyectados en el flujo de trabajo de desarrollo relevante con una presentaci贸n de parche al rastreador de problemas ANC aplicable. + +### Paso 2: Proponer un ACP a trav茅s de una solicitud de extracci贸n (PR) + +Una vez que el autor se siente seguro de que una idea tiene una buena oportunidad de ser aceptada, se debe redactar un ACP y enviarlo como una solicitud de extracci贸n (PR). Este borrador debe estar escrito en estilo ACP como se describe a continuaci贸n. Se recomienda encarecidamente que un solo ACP contenga una sola propuesta clave o una nueva idea. Cuanto m谩s enfocado est茅 el ACP, m谩s 茅xito tiende a tener. Si tienes dudas, divide tu ACP en varios enfoques bien definidos. El n煤mero de PR del ACP se convertir谩 en su n煤mero asignado. + +### Paso 3: Construir consenso en las Discusiones de GitHub y proporcionar una implementaci贸n (si corresponde) + +Los ACPs ser谩n fusionados por los mantenedores de ACPs si la propuesta est谩 generalmente bien formateada y coherente. Los editores de ACPs intentar谩n fusionar cualquier cosa que valga la pena discutir, independientemente de la viabilidad o complejidad, que no sea un duplicado o est茅 incompleto. Despu茅s de que un ACP se fusiona, se abrir谩 una Discusi贸n oficial de GitHub para el ACP y se vincular谩 a la propuesta para su discusi贸n comunitaria. Se recomienda que el autor o miembros de la Comunidad Avalanche de apoyo publiquen un resumen no t茅cnico acompa帽ante de su ACP para consumo general en esta Discusi贸n de GitHub. El ACP debe ser revisado y ampliamente apoyado antes de que se inicie una implementaci贸n de referencia, nuevamente para evitar desperdiciar el tiempo del autor y de la comunidad Avalanche, a menos que una implementaci贸n de referencia ayude a las personas a estudiar el ACP. + +### Paso 4: Marcar el ACP como `Implementable` a trav茅s de una solicitud de extracci贸n (PR) + +Una vez que un ACP es considerado completo por el autor, debe ser marcado como `Implementable`. En este punto, todas las preguntas abiertas deben ser abordadas y se debe proporcionar una implementaci贸n de referencia asociada (si corresponde). Como se mencion贸 anteriormente, la Fundaci贸n Avalanche se re煤ne peri贸dicamente para recomendar la ratificaci贸n de ACPs espec铆ficos, pero en 煤ltima instancia, depende de los miembros de la Red/Comunidad Avalanche adoptar los ACPs que apoyan ejecutando un Cliente de Red Avalanche compatible (ANC), como [AvalancheGo](https://github.com/ava-labs/avalanchego). + +### [Opcional] Paso 5: Marcar el ACP como `Stale` a trav茅s de una solicitud de extracci贸n (PR) + +Un ACP puede ser reemplazado por un ACP diferente, volviendo el original obsoleto. Si esto ocurre, el ACP original se marcar谩 como `Stale`. Los ACPs tambi茅n pueden ser marcados como `Stale` si el autor abandona el trabajo en 茅l durante un per铆odo prolongado de tiempo (12+ meses). Los ACPs pueden ser reabiertos y movidos de vuelta a `Proposed` si el autor reinicia el trabajo. + +## 驴Qu茅 debe incluir un ACP exitoso? + +Cada ACP debe tener las siguientes partes: + +- `Preambulo`: Tabla en formato Markdown que contiene metadatos sobre el ACP, incluyendo el n煤mero del ACP, un t铆tulo descriptivo corto, el autor y opcionalmente la informaci贸n de contacto de cada autor, etc. +- `Resumen`: Descripci贸n concisa (~200 palabras) del ACP +- `Motivaci贸n`: Justificaci贸n para adoptar el ACP y el problema/especificidad/oportunidad espec铆fica que aborda +- `Especificaci贸n`: Descripci贸n completa de la sem谩ntica de cualquier cambio que permita a cualquier miembro de la ANC/Comunidad Avalanche implementar el ACP +- `Consideraciones de seguridad`: Implicaciones de seguridad del ACP propuesto + +Cada ACP puede tener las siguientes partes: + +- `Preguntas abiertas`: Preguntas que deben resolverse antes de la implementaci贸n + +Cada ACP de `Ruta de est谩ndares` debe tener las siguientes partes: + +- `Compatibilidad hacia atr谩s`: Lista de cambios incompatibles hacia atr谩s requeridos para implementar el ACP y su impacto en la Comunidad Avalanche +- `Implementaci贸n de referencia`: C贸digo, documentaci贸n y telemetr铆a (de una red local) del cambio de ACP + +Cada ACP de `Ruta de mejores pr谩cticas` puede tener las siguientes partes: + +- `Compatibilidad hacia atr谩s`: Lista de cambios incompatibles hacia atr谩s requeridos para implementar el ACP y su impacto en la Comunidad Avalanche +- `Implementaci贸n de referencia`: C贸digo, documentaci贸n y telemetr铆a (de una red local) del cambio de ACP + +### Formatos y plantillas de ACP + +Cada ACP tiene asignado un subdirectorio 煤nico en el directorio `ACPs`. El nombre de este subdirectorio debe tener la forma `N-T` donde `N` es el n煤mero del ACP y `T` es el t铆tulo del ACP con cualquier espacio reemplazado por guiones. Los ACPs deben estar escritos en formato [markdown](https://daringfireball.net/projects/markdown/syntax) y almacenados en `ACPs/N-T/README.md`. Por favor, consulta la [plantilla de ACP](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/TEMPLATE.md) para ver un ejemplo del dise帽o correcto. + +### Archivos auxiliares + +Los ACPs pueden incluir archivos auxiliares como diagramas o fragmentos de c贸digo. Dichos archivos deben almacenarse en el subdirectorio del ACP (`ACPs/N-T/*`). No hay una convenci贸n de nomenclatura requerida para los archivos auxiliares. + +### Derechos de autor renunciados + +Los autores de los ACPs deben renunciar a cualquier reclamo de derechos de autor antes de que un ACP se fusione en el repositorio. Esto se puede hacer incluyendo el siguiente texto en un ACP: + +```text +## Derechos de autor + +Derechos de autor y derechos relacionados renunciados a trav茅s de [CC0](https://creativecommons.org/publicdomain/zero/1.0/). +``` + +## Contribuciones + +Antes de contribuir a los ACPs, por favor lee los [T茅rminos de Contribuci贸n de los ACPs](https://github.com/avalanche-foundation/ACPs/blob/main/CONTRIBUTING.md).