Archway Improvement Proposals (AIPs)

[zanicar]

Photo by CHUTTERSNAP on Unsplash

Introduction

Archway is a blockchain protocol that follows a design-driven approach to development. Changes to the protocol must be discussed and formally documented before being implemented. The protocol repository contains the set of Architecture Decision Records (ADRs) that formally document the development of the protocol.

This document describes the process for proposing, documenting, and implementing technical changes to the Archway project.

Proposal Process

The purpose of the proposal process is to evaluate and either accept or reject them.

Criteria

Every proposal needs to be assessed on the following criteria:

1. Functional Feasibility - must identify the core value proposition of the proposal and how it benefits the overall project/protocol. This must include operational considerations, economic impact, and legal considerations;
2. Strategic Fit - must correlate the outcome of implementing the proposal with the current strategic objectives and direction of the overall project and prioritize accordingly;
3. Technical Feasibility - must identify the technical requirements and dependencies for implementation of the proposal, including estimated timelines related to any such dependencies as well as any associated technical and security risks;
4. Impact - must identify the impact of implementation regarding downstream dependencies and incurred technical debt;

Process

1. Start the proposal process via an RFC (Request For Comment) on GitHub Discussions under Ideas. This serves to gauge both functional feasibility and strategic fit before going down deep technical rabbit holes;
2. Create an Issue as a Feature Request or General Issue and tag it as a “proposal”. Include the “draft” tag if the proposal is incomplete or a work in progress. Remove the “draft” tag once it is ready for review. A detailed design may not be required at this time;
3. Engage in constructive and thoughtful discussion and coordinate with other contributors on the issue.
4. Provide a detailed design specification to accompany the proposal if the “details” tag is added, indicating that a detailed design is requested. The detailed design may be described in the issue discussion or provided as an external reference;
5. Add the “final” tag once the discussion concludes and concerns have been addressed;
6. The proposal is evaluated and tagged as “accepted” or “rejected”. In either case, a clear rationale is provided to substantiate the outcome.

Definitions

• A proposal is a suggestion documented as a GitHub Issue denoted by the “proposal” tag;
• A detailed design specification is an expanded form of a proposal when a more careful explanation or consideration is required;

Expectations

• Every proposal should be given careful consideration based on the merits, metrics, and criteria relevant to the issue at hand at the time of review;
• All past proposals should be readily available and accessible to avoid duplication;
• Proposals should clearly communicate their intent (reason), value (benefit), and impact (consequences);
• Detailed design specifications should expand on the above by addressing any issues or concerns that may arise during the initial general discussion;

Help

Please feel free to engage with Archway’s official contributors and/or the greater community for help or assistance with this process. To learn more about general contributions to Archway, please review Archway Discussions - Contributing.

Examples

• RFC: Contract Registry Module
• Feature Request: Enhancing Querying and Withdrawals of Rewards