From 70f8511b20c9bd082d29cbdeb236e8f024cc2a44 Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Wed, 12 Feb 2025 16:58:19 +0100 Subject: [PATCH] Add IIP-1 Describes the Iota Improvement Proposal Process --- .github/markdownlint-config.yml | 4 + .github/workflows/gh-mdbook.yml | 59 +++++++ .github/workflows/markdownlint.yml | 18 +++ .gitignore | 13 ++ CONTRIBUTE.md | 28 ++++ LICENSE-APACHE | 201 ++++++++++++++++++++++++ README.md | 41 ++++- TEMPLATE.md | 46 ++++++ book.toml | 5 + format-iip-header.sh | 16 ++ generate-book.sh | 34 ++++ iips/IIP-0001/iip-0001.md | 242 +++++++++++++++++++++++++++++ iips/IIP-0001/process.svg | 3 + 13 files changed, 709 insertions(+), 1 deletion(-) create mode 100644 .github/markdownlint-config.yml create mode 100644 .github/workflows/gh-mdbook.yml create mode 100644 .github/workflows/markdownlint.yml create mode 100644 .gitignore create mode 100644 CONTRIBUTE.md create mode 100644 LICENSE-APACHE create mode 100644 TEMPLATE.md create mode 100644 book.toml create mode 100755 format-iip-header.sh create mode 100755 generate-book.sh create mode 100644 iips/IIP-0001/iip-0001.md create mode 100644 iips/IIP-0001/process.svg diff --git a/.github/markdownlint-config.yml b/.github/markdownlint-config.yml new file mode 100644 index 0000000..b53f0c1 --- /dev/null +++ b/.github/markdownlint-config.yml @@ -0,0 +1,4 @@ +default: false # excludes all rules by default + +# Files should end with a single newline character +MD047: true diff --git a/.github/workflows/gh-mdbook.yml b/.github/workflows/gh-mdbook.yml new file mode 100644 index 0000000..dbfba69 --- /dev/null +++ b/.github/workflows/gh-mdbook.yml @@ -0,0 +1,59 @@ +name: IIP Book + +on: + push: + branches: + - main + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v2 + + # Install Rust package manager + # + - name: Install cargo + uses: actions-rs/toolchain@v1 + with: + toolchain: stable + profile: minimal + + # Cache installation assets + # + - name: Cache cargo registry + uses: actions/cache@v1 + with: + path: ~/.cargo/registry + key: ${{ runner.os }}-cargo-registry-${{ hashFiles('**/Cargo.lock') }} + - name: Cache cargo index + uses: actions/cache@v1 + with: + path: ~/.cargo/git + key: ${{ runner.os }}-cargo-index-${{ hashFiles('**/Cargo.lock') }} + - name: Cache cargo build + uses: actions/cache@v1 + with: + path: target + key: ${{ runner.os }}-cargo-build-target-${{ hashFiles('**/Cargo.lock') }} + + # Install mdbook and requirements + # + - name: Install mdbook + uses: actions-rs/cargo@v1 + with: + command: install + args: mdbook + + - name: Generate summary + run: ./generate-book.sh + + # HTML publication as Github Page + # + - name: Publish HTML + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./book + publich_branch: ${{ github.ref }} diff --git a/.github/workflows/markdownlint.yml b/.github/workflows/markdownlint.yml new file mode 100644 index 0000000..bbee8e5 --- /dev/null +++ b/.github/workflows/markdownlint.yml @@ -0,0 +1,18 @@ +name: Markdown Lint + +on: + pull_request: + branches: [ main ] + + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v2 + - name: Markdown Linting + uses: avto-dev/markdown-lint@v1.5.0 + with: + config: './.github/markdownlint-config.yml' + args: './iips/**/*.md' diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..74af87b --- /dev/null +++ b/.gitignore @@ -0,0 +1,13 @@ +book/ +src/ +.idea/ + + +# Misc +.DS_Store +.env.local +.env.development.local +.env.test.local +.env.production.local + + diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md new file mode 100644 index 0000000..5ccf960 --- /dev/null +++ b/CONTRIBUTE.md @@ -0,0 +1,28 @@ +> **Note** +> This guide is meant for local development and contributing to the repository only, for guidance on the IIPs process and how to propose Tangle improvements, please see the [README](README.md) + + +# Documentation + +The IIPs online documentation is built using [Docusaurus 2](https://docusaurus.io/). The deployment is done through a centralized build from [IOTA WIKI](https://github.com/iota-wiki/iota-wiki). To run a local instance, the [IOTA WIKI CLI](https://www.npmjs.com/package/@iota-wiki/cli) is used. + +## Prerequisites + +- [Node.js 16.10 or above](https://nodejs.org/en/download/). +- [Modern Yarn](https://yarnpkg.com/getting-started/install) enabled by running `corepack enable`. + +## Installation + +```console +yarn +``` + +This command installs all necessary dependencies. + +## Local Development + +```console +yarn start +``` + +This command starts a local, wiki themed development server and opens up a browser window. Most changes are reflected live without having to restart the server. diff --git a/LICENSE-APACHE b/LICENSE-APACHE new file mode 100644 index 0000000..187345a --- /dev/null +++ b/LICENSE-APACHE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2019 IOTA Foundation + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/README.md b/README.md index bd9accc..04c7605 100644 --- a/README.md +++ b/README.md @@ -1 +1,40 @@ -# iip \ No newline at end of file +# IOTA Improvement Proposal (IIP) Repository + +IIPs are improvement proposals for bettering the IOTA technology stack. + +Building the IOTA ecosystem is a community effort, therefore we welcome anyone to propose, discuss and debate ideas that will later become formalized IIPs. + +## Propose new ideas + +Do you have an idea how to improve the IOTA technology stack? +- Head over to the [discussions](https://github.com/iotaledger/iips/discussions) page to browse already submitted ideas or share yours! +- Once your idea is discussed, you can submit a draft IIP ([template here](https://github.com/iotaledger/iips/blob/main/TEMPLATE.md) as a PR to the repository. +- You will receive feedback from the IIP Editors, core devs and community members to refine your proposal. +- Once accepted, your IIP is merged as Draft. +- It is your responsibility to drive its implementation and to present a clear plan on how the new feature will be adopted by the network. +- Once implementation is ready and testing yields satisfactory result, the IIP becomes Proposed. +- Proposed IIPs that are supported by majority of the network become Active. + +You may find more information about the IIP Process in [IIP-1](./iips/IIP-0001/iip-0001.md). + +## List of IIPs + + - Last updated: 2025-02-12 + - The _Status_ of a IIP reflects its current state with respect to its progression to being supported on the IOTA Mainnet. + - `Draft` IIPs are work in progress. They may or may not have a working implementation on a testnet. + - `Proposed` IIPs are demonstrated to have a working implementation on the IOTA Devnet or Testnet. + - `Active` IIPs are supported on the IOTA Mainnet. + - `Replaced` IIPs have been replaced by a newer IIP. + - `Obsolete` IIPs are no longer in use. + +![image](iips/IIP-0001/process.svg) + + +| # | Title | Description | Type | Layer | Status | Initial Target | +|----|---------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|-----------|-----------|--------------------|----------------| +| 1 | [IIP Process](iips/IIP-0001/iip-0001.md) | Purpose and guidelines of the contribution framework | Process | - | Active | - | + + +## Need help? + +If you want to get involved in the community, need help getting started, have any issues related to the repository or just want to discuss blockchain, distributed ledgers, and IoT with other people, feel free to join our [IOTA Builder Discord](https://discord.gg/iota-builders). diff --git a/TEMPLATE.md b/TEMPLATE.md new file mode 100644 index 0000000..02d9941 --- /dev/null +++ b/TEMPLATE.md @@ -0,0 +1,46 @@ +--- +iip: +title: +description: +author: , FirstName (@GitHubUsername) and GitHubUsername (@GitHubUsername)> +discussions-to: +status: Draft +type: +layer (*only required for Standards Track): +created: +requires (*optional): +replaces (*optional): +superseded-by (*optional): +--- + +This is the suggested template for new IIPs. + +Note that an IIP number will be assigned by an editor. When opening a pull request to submit your IIP, please use an abbreviated title in the filename, `iip-draft_title_abbrev.md`. + +The title should be 44 characters or less. It should not repeat the IIP number in title, irrespective of the category. + +## Abstract +Abstract is a multi-sentence (short paragraph) technical summary. This should be a very terse and human-readable version of the specification section. Someone should be able to read only the abstract to get the gist of what this specification does. + +## Motivation +The motivation section should describe the "why" of this IIP. What problem does it solve? Why should someone want to implement this standard? What benefit does it provide to the IOTA ecosystem? What use cases does this IIP address? + +## Specification +The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119. + +The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations for any of the current IOTA platforms (TODO: link to wiki). + +## Rationale +The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages. + +## Backwards Compatibility +All IIPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The IIP must explain how the author proposes to deal with these incompatibilities. IIP submissions without a sufficient backwards compatibility treatise may be rejected outright. + +## Test Cases +Test cases for an implementation are mandatory for IIPs that are affecting consensus changes. If the test suite is too large to reasonably be included inline, then consider adding it as one or more files in the IIPs directory. + +## Reference Implementation +An optional section that contains a reference/example implementation that people can use to assist in understanding or implementing this specification. If the implementation is too large to reasonably be included inline, then consider adding it as one or more files in the IIPs directory. + +## Copyright +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). diff --git a/book.toml b/book.toml new file mode 100644 index 0000000..1520a3d --- /dev/null +++ b/book.toml @@ -0,0 +1,5 @@ +[book] +title = "The Iota Improvement Proposal (IIP) Book" + +[output.html] +no-section-label = true \ No newline at end of file diff --git a/format-iip-header.sh b/format-iip-header.sh new file mode 100755 index 0000000..54a613e --- /dev/null +++ b/format-iip-header.sh @@ -0,0 +1,16 @@ +C=0 +touch tmp +while IFS= read -r line +do + if [[ $line == "---" && "$C" -eq 0 ]]; then + ((C++)) + line="
"
+  fi
+    if [[ $line == "---" && "$C" -eq 1 ]]; then
+        ((C++))
+        line="
" + fi + echo "$line" >> tmp +done < "$1" + +mv tmp $1 \ No newline at end of file diff --git a/generate-book.sh b/generate-book.sh new file mode 100755 index 0000000..38d54f5 --- /dev/null +++ b/generate-book.sh @@ -0,0 +1,34 @@ +#!/usr/bin/env bash + +# SPDX-License-Identifier: Apache-2.0 +# Source: https://github.com/rust-lang/rfcs/blob/85c95c7179acc8986eae709f773ff3a91f1e2e43/generate-book.sh + +set -e + +rm -rf src +mkdir src +cp -r iips src + +printf '[Introduction](introduction.md)\n\n' > src/SUMMARY.md + +# create summary, extract iip titles and numbers +find ./src ! -type d -name '*.md' ! -path ./src ! -path ./src/SUMMARY.md -print0 \ + | sed -e 's/.\/src\///g' \ + | sort -z \ + | while read -r -d '' file; +do + iipNum=$(sed 's/-0*/-/' <<< $(basename "$file" ".md")) + printf -- '- [%s%s](%s)\n' ${iipNum^^} "$(sed -n 's/^title:\(.*\)$/\1/p' < $file)" "$file" +done >> src/SUMMARY.md + +# remove "---" from iip header and replace it h 
 and
+find ./src ! -type d -name '*.md' ! -path ./src ! -path ./src/SUMMARY.md -print0 \ + | sort -z \ + | while read -r -d '' file; +do + ./format-iip-header.sh $file +done + +ln -fs README.md src/introduction.md + +mdbook build diff --git a/iips/IIP-0001/iip-0001.md b/iips/IIP-0001/iip-0001.md new file mode 100644 index 0000000..3a19bf9 --- /dev/null +++ b/iips/IIP-0001/iip-0001.md @@ -0,0 +1,242 @@ +--- +iip: 1 +title: IIP Process +description: Purpose and guidelines of the contribution framework +author: Levente Pap (@lzpap) +discussions-to: https://github.com/iotaledger/iips/discussions +status: Active +type: Process +created: 2025-02-12 +--- + +## Abstract + +An IOTA Improvement Proposal (IIP) is a design document providing information to the IOTA community, or describing a new feature for IOTA or its processes or environment. The IIP should provide a concise technical specification of the feature and a rationale for the feature. + +IIPs are the primary mechanism for proposing new features and standards to the IOTA protocol and related applications, furthermore for collecting input from the wider community and documenting the design decisions that go into the IOTA technology. + +IIPs are maintained as text files inside the repository, therefore the history and evolution of protocol features are transparent and well documented. + +This IIP defines the IIP Process itself to establish a common way of working. + +## Motivation + +The motivation of this IIP is to create a public platform to discuss improvement ideas related to the IOTA technology and define an easy-to-follow process of contributing to their development and implementation. + +## Specification + +### IIP Types + +There are 3 types of IIPs: + - A **Standards Track IIP** describes any change that affects most or all IOTA node implementations, such as a change to the network protocol, a change in transaction validity rules, or any change or addition that affects the interoperability of applications using IOTA. Standards Track IIPs consist of two parts, a design document and a reference implementation. Standards Track IIPs can be broken down into layers: + 1. **Core**: Changes or additions to core features of IOTA, including consensus, execution, storage, and account signatures + 2. **Networking**: Changes or additions to IOTA's mempool or network protocols + 3. **Interface**: Changes or additions to RPC or API specifications or lower-level naming conventions + 4. **Framework**: Changes or additions to IOTA Move contracts and primitives included within the codebase, such as within the IOTA Framework + 5. **Application**: Proposals of new IOTA Move standards or primitives that would not be included within the IOTA codebase but are of significant interest to the developer community + - An **Informational IIP** describes an IOTA design issue, or provides general guidelines or information to the IOTA community, but does not propose a new feature. Informational IIPs do not necessarily represent an IOTA community consensus or recommendation, so users and implementors are free to ignore Informational IIPs or follow their advice. + - A **Process IIP** describes a process surrounding IOTA, or proposes a change to (or an event in) a process. Process IIPs are like Standards Track IIPs but apply to areas other than the IOTA protocol itself. They may propose an implementation, but not to IOTA's codebase; they often require community consensus; unlike Informational IIPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, changes to the decision-making process, and changes to the tools or environment used in IOTA development. + +It is highly recommended that a IIP outlines a single key proposal, idea or feature; the narrower the scope of the IIP is, the easier it becomes to reach consensus on the proposed feature and incorporate it into the protocol. Several IIPs can form a bundle of changes when linked to each other. + +### IIP Format and Structure + +IIPs must adhere to the format and structure requirements that are outlined in this document. A IIP is written in [Markdown](https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) format and should have the following parts (optional parts are marked with a *): + +| Name | Description | +|---------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Preamble | [RFC 822](https://www.ietf.org/rfc/rfc822.txt) style headers containing metadata about the IIP, including the IIP number, a short descriptive title (limited to a maximum of 44 characters), a description (limited to a maximum of 140 characters), and the author details. Irrespective of the category, the title and description should not include IIP number. [See below](#iip-header-preamble) for details. | +| Abstract | A short summary of the technical issue being addressed by the IIP. | +| Motivation | A motivation section is critical for IIPs that want to change the IOTA protocol. It should clearly explain why the existing protocol specification is inadequate to address the problem that the IIP solves. IIP submissions without sufficient motivation may be rejected outright. | +| Specification | The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations for any of the current IOTA platforms. | +| Rationale | The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages. The rationale may also provide evidence of consensus within the community, and should discuss important objections or concerns raised during discussion. | +| Backwards Compatibility* | All IIPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The IIP must explain how the author proposes to deal with these incompatibilities. IIP submissions without a sufficient backwards compatibility treatise may be rejected outright. | +| Test Cases* | Test cases for an implementation are mandatory for IIPs that are affecting consensus changes. Tests should either be inlined in the IIP as data or placed in the IIP folder. | +| Reference Implementation* | An optional section that contains a reference/example implementation that people can use to assist in understanding or implementing this specification. | +| Copyright | All IIPs must be in the public domain. See the bottom of this IIP for an example copyright waiver. | + +### IIP Template + +The template to follow for new IIPs is located in the [repository](https://github.com/iotaledger/iips/blob/main/TEMPLATE.md). + +### IIP Process + +Parties involved in the process are: + - _IIP author_: you, the champion who proposes a new IIP. It is the responsibility of the _IIP author_ to drive the progression of the IIP to `Active` status. This includes initiating public discussion and implementing the proposal as well. + - _IIP editor_: they deal with administering the IIP process and ensure process requirements are fulfilled. + - _Technical Committee_: technical experts of IOTA who evaluate new IIPs, provide feedback and ensure that only sound and secure features are added to the protocol. + +#### IIP Statuses + +The status of the IIP describes its current stage in the IIP process. + +| Status | Description | +|-----------|---------------------------------------------------------------------------------------------------------------| +| Idea | An idea for an improvement to the IOTA technology. Not yet tracked as an official IIP. | +| Draft | The idea has been formally accepted in the repository, and is being worked on by its authors. | +| Proposed | The IIP has a working implementation and has clear plans on how to progress to `Active` status. | +| Active | The IIP is deployed to the main network or some IIP specific adoption criteria has been met. | +| Deferred | The _IIP author(s)_ are not working on the IIP currently, but plan to continue in the future. IIP is on hold. | +| Rejected | The IIP is rejected. | +| Withdrawn | The IIP has been withdrawn by the _IIP author(s)_. | +| Replaced | The IIP is replaced by a newer IIP. Must point to the new IIP in the header. | +| Obsolete | The IIP is rendered obsolete by some future change. | + +#### IIP Workflow + +_How are new proposal get added to the protocol?_ + +1. All IIPs begin life as an `Idea` proposed in the public [IOTA discussion forum, that is the GitHub Discussion page of the IIP repository](https://github.com/iotaledger/iips/discussions). A public, open discussion should predate any formal IIP submission. If you want to propel your proposal to acceptance, you should make sure to build consensus and support in the community around your proposed changes already in the idea stage. + + +2. Once the idea has been vetted, your next task is to submit a `Draft` IIP to the IIP repository as a pull request. Do not assign a IIP number yet to the draft, but make sure that the proposal is technically sound and follows the format and style guides of the IIP Process. Create a sub-folder under `iips` folder with the title of the draft (`iips/title_of_draft/`) and put all assets in this folder. + + +3. A _IIP editor_ reviews your PR and assigns a IIP number to the draft. + + +4. The _Technical Committee_ as well as the broader public evaluate the draft proposal and might ask for modifications or clarifications. The proposal can only be merged into the repository as a draft if it represents a net improvement and does not complicate the protocol unduly. + + +5. The IIP is merged into the repo with `Draft` status by _IIP editor/author_. + + +6. When a working implementation is presented and there are clear plans on how to progress the IIP to completion, the _IIP author_ submits a subsequent PR that links its implementation to the IIP and progresses it to `Proposed` stage. The IIP is ready to be deployed on testnet. + + +7. When a `Proposed` IIP is deemed to have met all appropriate criteria and its implementation has been demonstrated to work reliably in testnet environment, it is ready to be moved to the main network. Upon deployment, the IIP status must change to `Active`. + +_How can a IIP transition from one status to another?_ + +![image](./process.svg) + +A `Draft` IIP might be moved to `Deferred` status by the _IIP author(s)_ when they are no longer working on the proposal, but plan to continue it in the future. _IIP editors_ might also move any IIPs to `Deferred` if the proposal is not making progress. + +A `Draft` IIP might be moved to `Withdrawn` status by the _IIP author(s)_. + +A `Draft` IIP might be moved to `Rejected` status by _IIP editor(s)_ or _Technical Committee_ if it does not meet the appropriate IIP criteria, or no relevant progress has been demonstrated on the IIP for at least 3 years. + +A `Draft` IIP might be moved to `Proposed` status by IIP author(s) if it is considered complete, has a working implementation and clear plans on how to progress it to `Active` status. + +A `Proposed` IIP might be moved to `Active` status if a IIP specific adoption criteria has been met. For Core IIPs this means deployment on the main network. + +A `Proposed` IIP might be moved to `Rejected` status by _IIP editor(s)_ or _Technical Committee_ if its implementation puts unduly burden and complexity on the protocol, or other significant problems are discovered during testing. + +An `Active` IIP might be moved to `Replaced` status by a newer IIP. The replaced IIP must point to the IIP that replaces it. + +An `Active` IIP might be moved to `Obsolete` status when the feature is deprecated. + +_How to champion the IIP Process as a IIP author?_ + + - Browse the [idea discussion forum](https://github.com/iotaledger/iips/discussions) before posting a new IIP idea. Someone else might already have proposed your idea, or a similar one. Take inspiration from previous ideas and discussions. + - It is your responsibility as a _IIP author_ to build community consensus around your idea. Involve as many people in the discussion as you can. Use social media platforms, Discord or Reddit to raise awareness of your idea. + - Submit a draft IIP as a PR to the IIP repository. Put extra care into following IIP guidelines and formats. IIPs must contain a link to previous discussions on the topic, otherwise your submissions might be rejected. IIPs that do not present convincing motivation, demonstrate lack of understanding of the design's impact, or are disingenuous about the drawbacks or alternatives tend to be poorly-received. + - Your draft IIP gets a IIP number assigned by a _IIP editor_ and receives review and feedback from the larger community as well as from the _Technical Committee_. Be prepared to revise your draft based on this input. + - IIPs that have broad support are much more likely to make progress than those that don't receive any comments. Feel free to reach out to the _IIP editors_ in particular to get help to identify stakeholders and obstacles. + - Submitted draft IIPs rarely go through the process unchanged, especially as alternatives and drawbacks are shown. You can make edits, big and small, to the draft IIP to clarify or change the design, but make changes as new commits to the pull request, and leave a comment on the pull request explaining your changes. Specifically, do not squash or rebase commits after they are visible on the pull request. + - When your draft IIP PR gets enough approvals from _IIP editors_ and _Technical Committee_ members, it can be merged into the repository, however, your job is far from complete! To move the draft into the next status (proposed), you have to demonstrate a working implementation of your IIP. For Core IIPs, seek help from protocol developers and/or client teams to coordinate the feature implementation. For IRCs for example you need to provide their implementation yourself. + - You also need to present a clear plan on how the IIP will be moved to the `Active` status, by for example agreeing on a IIP deployment strategy with the _Technical Committee_ or core developers. + - To move your `Draft` IIP to the `Proposed` phase, submit a subsequent PR that links its implementation and devises its route to become `Active`. The latter might be an additional document in the IIP's folder, a link to a public discussion or a short description or comment on the PR itself. + - To move your `Proposed` IIP to `Active` status you need to demonstrate that it has met its specific adoption criteria. For Core IIPs, this means that majority of network nodes support it. For other IIPs, especially for IRCs, adoption might mean that the standard is publicly available, well documented and there are applications building on it. + +### IIP Header Preamble + +Each IIPs must have an RFC 822 style header preamble preceded and followed by three hyphens (---). The headers must appear in the following order. Headers marked with "*" are optional and are described below. All other headers are required. + +| Field | Description | +|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `iip` | IIP number, or "?" before being assigned (assigned by _IIP editor_) | +| `title` | Few words describing the IIP, maximum 44 characters | +| `description*` | One full short sentence | +| `author` | A comma separated list of the author's or authors' name + GitHub username (in parenthesis), or name and email (in angle brackets). Example, FirstName LastName (@GitHubUsername), FirstName LastName , FirstName (@GitHubUsername) and GitHubUsername (@GitHubUsername) | +| `discussions-to*` | The url pointing to the official discussion thread | +| `status` | Current status of the IIP. One of: `Draft`, `Proposed`, `Active`, `Deferred`, `Rejected`, `Withdrawn`, `Obsolete` or `Replaced` | +| `type` | IIP type, one of: `Standards Track`, `Process` or `Informational` | +| `layer*` | Only for Standards Track, defines layer: `Core`, `Networking`, `Interface`, `Framework` or `Application` | +| `created` | Date created on, in ISO 8601 (yyyy-mm-dd) format | +| `requires*` | Link dependent IIPs by number | +| `replaces*` | Older IIP being replaced by this IIP | +| `superseded-by*` | Newer IIP replaces this IIP | +| `withdrawal-reason*` | A sentence explaining why the IIP was withdrawn. (Optional field, only needed when status is `Withdrawn`) | +| `rejection-reason*` | A sentence explaining why the IIP was rejected. (Optional field, only needed when status is `Rejected`) | + +### Linking IIPs +References to other IIPs should follow the format IIP-N where N is the IIP number you are referring to. Each IIP that is referenced in an IIP MUST be accompanied by a relative Markdown link the first time it is referenced, and MAY be accompanied by a link on subsequent references. The link MUST always be done via relative paths so that the links work in this GitHub repository or forks of this repository. For example, you would link to this IIP with `[IIP-1](../IIP-0001/iip-0001.md)`. + +### Auxiliary Files +Images, diagrams and auxiliary files should be included in the subdirectory of the IIP. When linking to an image in the IIP, use relative links such as `[IIP Process Diagram](../IIP-0001/process.png)`. + +### Linking to external resources +External links should not be included, except to the IOTA repository. + +### Transferring IIP Ownership + +It occasionally becomes necessary to transfer ownership of IIPs to a new champion. In general, we'd like to retain the original author as a co-author of the transferred IIP, but that's really up to the original author. A good reason to transfer ownership is because the original author no longer has the time or interest in updating it or following through with the IIP process, or has fallen off the face of the 'net (i.e. is unreachable or isn't responding to email). A bad reason to transfer ownership is because you don't agree with the direction of the IIP. We try to build consensus around a IIP, but if that's not possible, you can always submit a competing IIP. + +If you are interested in assuming ownership of a IIP, send a message asking to take over, addressed to both the original author and the _IIP editors_. If the original author doesn't respond to the email in a timely manner, the _IIP editors_ will make a unilateral decision (it's not like such decisions can't be reversed :)). + +### IIP Editors + +The current IIP editors are: + - Lucas Tortora (lucas.tortora@iota.org) + - Kevin Mayrhofer (kevin.mayrhofer@iota.org) + - Gino Osahon (gino.osahon@iota.org) + - Salaheldin Soliman (salaheldin.soliman@iota.org) + - Levente Pap (@lzpap, levente.pap@iota.org) + +| Name | GitHub username | Email address | Affiliation | +|:-------------------|:------------------|:----------------------------|:----------------| +| Kevin Mayrhofer | Dr-Electron | kevin.mayrhofer@iota.org | Iota Foundation | +| Gino Osahon | Ginowine | gino.osahon@iota.org | Iota Foundation | +| Lucas Tortora | lucas-tortora | lucas.tortora@iota.org | Iota Foundation | +| Salaheldin Soliman | salaheldinsoliman | salaheldin.soliman@iota.org | Iota Foundation | +| Levente Pap | lzpap | levente.pap@iota.org | Iota Foundation | + + + +### IIP Editor Responsibilities + +IIP editors' essential role is to assist and guard the process of contributing to the IOTA ecosystem, provide help and directions to community members as well as to external contributors. If you have a question regarding the IIP process, reach out to them, they will point you to the right direction. + +They ensure that only quality contributions are added as IIPs, provide support for IIP authors, furthermore monitor that the IIP process is fair, objective and well documented. + +For each new IIP that comes in, an editor does the following: + - Read the IIP to check if it is ready: sound and complete. The ideas must make technical sense, even if they don't seem likely to get to `Active` status. + - The title should accurately describe the content. + - Check the IIP for language (spelling, grammar, sentence structure, etc.), markup (GitHub flavored Markdown), code style. + +If the IIP isn't ready, the editor will send it back to the author for revision, with specific instructions. + +Once the IIP is ready to be merged as a draft, the editor will: + - Assign a IIP number that does not conflict with other IIP numbers. It might be the PR number, but might also be selected as the next unused IIP number in line. + - Merge the corresponding pull request. + - Send a message back to the IIP author with the next step. + +The editors don't pass judgment on IIPs. We merely do the administrative & editorial part. + +### Technical Committee + +The _Technical Committee_ consists of several core contributors of the IOTA ecosystem and core developers. Their job is to evaluate technical details of IIPs, judge their technical feasibility and safeguard the evolution of the protocol. Core improvement ideas must be carefully thought through and their benefits must outweigh their drawbacks. + +In order for a draft IIP to be accepted into the repo, it must be signed-off by the _Technical Committee_. It is also the committee that gives the green light for drafts to become proposed or active. + +## Rationale + +The IIP process is intended to replace the formerly adopted Tangle Improvement Proposal (TIP) process due the underlying technological shift. + +TIPs refer to the previous generation of IOTA technology and hence are outdated. In order not to confuse contributors, IIP is introduced as a new process to propose, discuss and implement new ideas for the IOTA technology stack. + +In order not to reinvent the wheel, the IIP Process draws heavily on the [BIP](https://github.com/bitcoin/bips/blob/master/bip-0002.mediawiki) and [EIP](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1.md) processes. + +## Backwards Compatibility + - The current `iotaledger/tips` repository will be archived. + - All TIPs become `Obsolete` and are no longer in use. + +## References + - [BIP-1](https://github.com/bitcoin/bips/blob/master/bip-0001.mediawiki) and[ BIP-2](https://github.com/bitcoin/bips/blob/master/bip-0002.mediawiki), Bitcoin Improvement Proposal Purpose and Guidelines + - [EIP-1](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1.md), Ethereum Improvement Proposal Purpose and Guidelines + - [CIP-1](https://github.com/cardano-foundation/CIPs/tree/master/CIP-0001), Cardano Improvement Proposal Process + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). diff --git a/iips/IIP-0001/process.svg b/iips/IIP-0001/process.svg new file mode 100644 index 0000000..87ae6d7 --- /dev/null +++ b/iips/IIP-0001/process.svg @@ -0,0 +1,3 @@ + + +
Idea
Idea
Draft
Draft
Deferred
Deferred
Rejected
Rejected
Withdrawn
Withdrawn
Proposed
Proposed
Active
Active
Replaced
Replaced
Obsolete
Obsolete
Submit IIP
Submit...Viewer does not support full SVG 1.1 \ No newline at end of file