|
1 | 1 | --- |
2 | 2 | pip: 1 |
3 | 3 | title: PIP Purpose and Guidelines |
4 | | -status: Living |
5 | | -type: Meta |
6 | | -author: Javad Rajabzadeh <ja7ad@live.com> |
| 4 | +status: Active |
| 5 | +type: Process |
| 6 | +author: Pactus Development Team <info@pactus.org> |
7 | 7 | created: 2023-07-10 |
8 | 8 | --- |
9 | 9 |
|
10 | | -## What is an PIP? |
| 10 | +## What is a PIP? |
11 | 11 |
|
12 | | -Pactus Improvement Proposals (PIPs) serve as a comprehensive framework for outlining and defining the standards |
13 | | -for the Pactus platform's ongoing development and enhancement. These proposals cover various aspects of the platform, |
14 | | -including core protocol specifications and client application programming interfaces (APIs). By establishing a clear |
15 | | -and consistent set of guidelines, PIPs ensure seamless interoperability and extensibility across the Pactus ecosystem, |
16 | | -fostering a robust and efficient environment for developers and users alike. |
| 12 | +A Pactus Improvement Proposal, or PIP, is a design document that provides information or |
| 13 | +describes a new feature for the Pactus blockchain. |
| 14 | +The primary goal of a PIP is to encourage the development team to write down ideas before implementation and |
| 15 | +invite the community to contribute more efficiently. |
| 16 | +It also helps to brainstorm, review, and discuss changes and potential issues before |
| 17 | +they can impact the production environment. |
17 | 18 |
|
18 | | -## PIP Rationale |
| 19 | +## PIP workflow |
19 | 20 |
|
20 | | -We intend PIPs to be the primary mechanisms for proposing new features, for collecting community technical input on an issue, |
21 | | -and for documenting the design decisions that have gone into Pactus. |
22 | | -Because the PIPs are maintained as text files in a versioned repository, |
23 | | -their revision history is the historical record of the feature proposal. |
| 21 | +The PIP process starts with an idea for the Pactus blockchain. |
| 22 | +The author should document the idea in PIP format and explain it in simple and |
| 23 | +[plain English](https://plainenglish.co.uk/how-to-write-in-plain-english.html). |
| 24 | +The drafted PIP can then be submitted to the PIP repository. |
24 | 25 |
|
25 | | -For Pactus implementers, PIPs are a convenient way to track the progress of their implementation. |
26 | | -Ideally, each implementation maintainer would list the PIPs that they have implemented. |
27 | | -This will give end users a convenient way to know the current status of a given implementation or library. |
| 26 | +The PIP should be assigned a proper number and category before it gets merged. |
| 27 | +Once the PIP is merged into the repository, |
| 28 | +a [discussion](https://github.com/pactus-project/PIPs/discussions) page will be created for it. |
| 29 | +All discussions around the PIP will be conducted on this discussion page. |
| 30 | + |
| 31 | +Authors can update drafts as needed through pull requests until the PIP is approved. |
| 32 | +Once a PIP is approved, the implementation of the PIP can begin. |
| 33 | + |
| 34 | +## PIP Status |
| 35 | + |
| 36 | +The typical paths of the status of PIPs are as follows: |
| 37 | + |
| 38 | + |
| 39 | + |
| 40 | +- **Draft**: The PIP is in the initial stage and is being actively worked on. |
| 41 | + It is open for feedback and suggestions from the community. |
| 42 | + |
| 43 | +- **Accepted**: The PIP has been reviewed and accepted for implementation. |
| 44 | + It indicates that the idea has been thoroughly discussed and is ready to be worked on by developers. |
| 45 | + |
| 46 | +- **Final**: The PIP has been fully implemented and is now part of the Pactus protocol. |
| 47 | + It indicates that the changes proposed in the PIP are live and operational. |
| 48 | + |
| 49 | +- **Replaced**: The PIP has been replaced by a newer PIP. |
| 50 | + This typically happens when the proposed changes are superseded by a more effective or updated solution. |
| 51 | + |
| 52 | +- **Deferred**: The PIP is on hold and not currently being considered for implementation. |
| 53 | + It may be revisited in the future based on community needs and priorities. |
| 54 | + |
| 55 | +- **Withdrawn**: The PIP has been withdrawn by the author. |
| 56 | + This can occur if the author decides not to pursue the idea. |
| 57 | + |
| 58 | +- **Rejected**: The PIP has been reviewed and rejected. |
| 59 | + This status indicates that the proposed changes are not suitable for implementation within the Pactus protocol. |
| 60 | + |
| 61 | +- **Active**: The PIP is continually being updated and has not reached a state of finality. |
| 62 | + This status is typically reserved for documents that require ongoing updates and revisions, |
| 63 | + such as this document, PIP-1. |
| 64 | + |
| 65 | +## PIP format |
| 66 | + |
| 67 | +TODO: to complete |
28 | 68 |
|
29 | 69 | ## PIP Types |
30 | 70 |
|
31 | | -There are three types of PIP: |
| 71 | +There are types of a PIP: |
| 72 | + |
| 73 | +### Standards Track |
| 74 | + |
| 75 | +Standards Track PIPs propose changes to the Pactus blockchain's protocols, |
| 76 | +including improvements to the core protocol, network, or any other standards. |
32 | 77 |
|
33 | | -**Standards Track** PIP: |
34 | | -Describes any change that affects most or all Pactus implementations, such as—a change to the network protocol, |
35 | | -a change in block or transaction validity rules, proposed application standards/conventions, |
36 | | -or any change or addition that affects the interoperability of applications using Pactus. |
37 | | -Standards Track PIPs consist of three parts—a design document, an implementation, and |
38 | | -(if warranted) an update to the formal specification. |
39 | | -Furthermore, Standards Track PIPs can be broken down into the following categories: |
| 78 | +### Informational |
40 | 79 |
|
41 | | -* *Core*: Improvements requiring a consensus fork, as well as changes that are not necessarily consensus critical but |
42 | | - may be relevant to "core dev" discussions or any change to transaction, block, address or their new versions. |
| 80 | +Informational PIPs describe Pactus design issues, guidelines, or general information |
| 81 | +that is not suitable for the Standards Track. |
| 82 | +They may also propose features or ideas for further discussion within the community. |
43 | 83 |
|
44 | | -* *Networking*: Includes improvements around Pactus networking protocol. |
| 84 | +### Process |
45 | 85 |
|
46 | | -* *Interface*: Includes improvements around clients, API/RPCs specifications, and how users and |
47 | | - applications interact with the blockchain. |
48 | | - The label "interface" aligns with the interfaces repo, and discussion should primarily occur |
49 | | - in that repository before a PIP is submitted to the PIPs repository. |
| 86 | +Process PIPs propose changes to the PIP process itself or suggest improvements to |
| 87 | +the decision-making process within the Pactus community. |
50 | 88 |
|
51 | | -* *PRC*: Application-level standards and conventions, including contract standards such as |
52 | | -* token standards, name registries, URI schemes, library/package formats, and wallet formats. |
| 89 | +## PIP Categories |
53 | 90 |
|
54 | | -**Meta PIP**: Describes a process surrounding Pactus or proposes a change to (or an event in) a process. |
55 | | -Process PIPs are like Standards Track PIPs but apply to areas other than the Pactus protocol itself. |
56 | | -They may propose an implementation, but not to Pactus's codebase; they often require community consensus; |
57 | | -unlike Informational PIPs, they are more than recommendations, and users are typically not free to ignore them. |
58 | | -Examples include procedures, guidelines, changes to the decision-making process, |
59 | | -and changes to the tools or environment used in Pactus development. |
60 | | -Any meta-PIP is also considered a Process PIP. |
| 91 | +Standards PIPs are categorized into the following layers: |
61 | 92 |
|
62 | | -**Informational** PIP: Describes a Pactus design issue, or provides general guidelines or |
63 | | -information to the Pactus community, but does not propose a new feature. |
64 | | -Informational PIPs do not necessarily represent Pactus community consensus or a recommendation, |
65 | | -so users and implementers are free to ignore Informational PIPs or follow their advice. |
| 93 | +### Core |
66 | 94 |
|
67 | | -It is highly recommended that a single PIP contain a single key proposal or new idea. |
68 | | -The more focused the PIP, the more successful it tends to be. |
69 | | -A change to one client doesn't require a PIP; a change that affects multiple clients, |
70 | | -or defines a standard for multiple apps to use, does. |
| 95 | +Core PIPs propose changes to the fundamental aspects of the Pactus protocol. |
| 96 | +These changes are critical and require careful consideration due to their potential impact on the entire network. |
71 | 97 |
|
72 | | -A PIP must meet certain minimum criteria. It must be a clear and complete description of the proposed enhancement. |
73 | | -The enhancement must represent a net improvement. The proposed implementation, |
74 | | -if applicable, must be solid and must not complicate the protocol unduly. |
| 98 | +### Networ |
75 | 99 |
|
76 | | -## PIP Status Terms |
| 100 | +Network PIPs focus on changes related to network communication. |
| 101 | +This includes improvements to the peer-to-peer protocol, network topology, and related networking functionalities. |
77 | 102 |
|
78 | | - |
| 103 | +### Interface |
79 | 104 |
|
80 | | -* Draft - Proposal under active discussion and revision. |
81 | | -* Accepted - Normative proposal accepted for implementation. |
82 | | -* Final - Accepted and implementation complete, or no longer active. |
83 | | -* Rejected - Formally declined and will not be accepted. |
84 | | -* Withdrawn - Removed from consideration by sponsor or authors. |
| 105 | +Interface PIPs propose changes to the external interfaces of the Pactus protocol, such as APIs. |
| 106 | +These changes impact how developers interact with the Pactus blockchain. |
0 commit comments