From 5e3a23a010d72744c27b7242ea2044c890855864 Mon Sep 17 00:00:00 2001 From: Serg Metelin Date: Wed, 16 Oct 2024 17:11:43 -0400 Subject: [PATCH 1/2] Update hip-1.md in preparation to Hiero migration - Adding Hiero TSC entity - Updating the process to reflect Hiero TSC - Grammar and styling fixes Signed-off-by: Serg Metelin --- HIP/hip-1.md | 124 ++++++++++++++++++++++++++------------------------- 1 file changed, 64 insertions(+), 60 deletions(-) diff --git a/HIP/hip-1.md b/HIP/hip-1.md index 78386f6c9..9e289cdb6 100644 --- a/HIP/hip-1.md +++ b/HIP/hip-1.md @@ -1,7 +1,7 @@ --- hip: 1 title: Hedera Improvement Proposal Process -author: Ken Anderson (@kenthejr), Serg Metelin (@sergmetelin), Simi Hunjan (@SimiHunjan) +author: Ken Anderson (@kenthejr), Serg Metelin (@sergmetelin), Simi Hunjan (@SimiHunjan), Michael Garber (@mgarbs) type: Process needs-council-approval: No status: Active @@ -14,11 +14,11 @@ updated: 2021-10-27 HIP stands for Hedera Improvement Proposal. A HIP is intended to provide information or initiate engineering efforts to update Hedera functionality. The HIP should be technically clear and concise. HIPs should be as granular as possible. Small targeted HIPs are more likely to reach consensus and result in a reference implementation. This may require breaking a bigger idea into smaller components. -HIPs are intended to be the primary mechanism for proposing new features, for collecting community input, and for documenting the design decisions that have gone into Hedera Hashgraph. The HIP author is responsible for building consensus within the community and documenting dissenting opinions. +HIPs are intended to be the primary mechanism for proposing new features, collecting community input, and documenting the design decisions that have gone into Hedera. The HIP author is responsible for building consensus within the community and documenting dissenting opinions. Because the HIPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal. -HIPs are not meant to address *bugs* in implemented code. Bugs should be addressed using issues on the implementation's repository. +HIPs are not meant to address bugs in implemented code. Bugs should be addressed using issues in the implementation's repository. ## HIP Types @@ -26,23 +26,27 @@ There are three kinds of HIP: 1. A **Standards Track** HIP describes a new feature or implementation for Hedera. It may also describe an interoperability standard that will be supported outside of the official Hedera node software stack. The Standards Track HIP abstract should include which part of the Hedera ecosystem it addresses. Standards Track HIPs require a specification and a reference implementation: - **a. Core:** This includes proposals addressing the Hashgraph algorithm, peer-to-peer networking, etc. These types of features are implemented on Hedera consensus nodes. + **a. Core:** This includes proposals addressing the Hashgraph algorithm, peer-to-peer networking, and other features implemented on Hedera consensus nodes. - **b. Service:** Hedera services sit on top of the Core node software and provide the functionalities that are accessed by users. These currently include the File Service, Consensus Service, Token Service, and Smart Contract Service. This type of proposal should be used to add to or improve the service-layer of Hedera. These types of features are implemented on Hedera consensus nodes. + **b. Service:** Hedera services sit on top of the Core node software and provide the functionalities that users access. These currently include the File Service, Consensus Service, Token Service, and Smart Contract Service. This type of proposal should be used to add to or improve Hedera's service layer. These features are implemented on Hedera consensus nodes. - **c. Mirror:** A mirror node runs software designed to retrieve all, or some of the records generated by the Hedera consensus nodes and make those records available to users in a way that is meaningful, reliable, and trustworthy. + **c. Mirror:** A mirror node runs software designed to retrieve all or some of the records generated by the Hedera consensus nodes and make those records available to users in a way that is meaningful, reliable, and trustworthy. - **d. Application:** Application standards may be used to standardize software in the Hedera ecosystem that aren't mirror or consensus nodes. This includes application network software, external contract consensus nodes, multi-sig oracles, persistence mechanisms, enterprise software plugins, etc. An example of an Application standard would be the Stablecoin Contract and Non-fungible Token Contract written in Java as a layer-2 solution using the Hedera Consensus service to maintain trust. + **d. Application:** Application standards may be used to standardize software in the Hedera ecosystem that does not affect Mirror or Consensus nodes. This includes application network software, external contract consensus nodes, multi-sig oracles, persistence mechanisms, enterprise software plugins, etc. An example of an Application standard would be the Stablecoin Contract and Non-fungible Token Contract written in Java as a layer-2 solution using the Hedera Consensus service to maintain trust. 2. An **Informational** HIP describes a Hedera design issue or provides general guidelines or information to the Hedera community but does not propose a new feature. Informational HIPs do not necessarily represent a Hedera community consensus or recommendation, so users and implementers are free to ignore Informational HIPs or follow their directions. -3. A **Process** HIP describes a process surrounding Hedera, or proposes a change to a process. Process HIPs are like Standards Track HIPs but apply to areas other than the node and ecosystem software codebases. They may propose an implementation, but not to Hedera's codebase; they often require community consensus; unlike Informational HIPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, and changes to the decision-making process. Any meta-HIP is also considered a Process HIP. +3. A **Process** HIP describes a process surrounding Hedera or proposes a change to a process. Process HIPs are like Standards Track HIPs but apply to areas other than the node and ecosystem software codebases. They may propose an implementation, but not to Hedera's codebase; they often require community consensus; unlike Informational HIPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, and changes to the decision-making process. Any meta-HIP is also considered a Process HIP. ## HIP Workflow -### Hedera Council +### Hiero Technical Steering Committee -The Hedera Council or "the Council" is made up of large organizations who participate in decisions related to the technical development roadmap, treasury management, and general governance. The Council has the final say on Core, Service, and Mirror node Standards Track HIPs. +The Technical Steering Committee (the “Hiero TSC”) is responsible for all technical oversight of the Hiero codebase. It has the final say on Core, Service, and Mirror node Standards Track HIPs, as well as Process HIPs. You can read more about Hiero and Hiero TSC here: https://github.com/hiero-ledger/hiero/blob/main/technical-charter.md + +### Hedera Council Technical Committee + +The Hedera Council, or "the Council," is made up of large organizations that participate in decisions related to the technical development roadmap, treasury management, and general governance. Its Technical Committee (Hedera TechComm) is composed of technical representation of Governing Council members and has the final say on what HIPs will be integrated into the Hedera public network. ### Hedera Core Developers @@ -58,7 +62,7 @@ The HIP process begins with a new idea for Hedera. It is highly recommended that Each HIP must have a champion -- someone who writes the HIP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The HIP champion (a.k.a. Author) should first attempt to ascertain whether the idea is HIP-able. Circulating the idea in Hedera's Discord server (https://hedera.com/discord) or in an issue in the Hedera HIP GitHub Repository (https://github.com/hashgraph/hedera-improvement-proposal) is the best way to do so. -Vetting an idea publicly before going as far as writing a HIP is meant to save the potential author time. Asking the community first if an idea is original helps avoid too much time being spent on something that may be rejected based on prior discussions. It also helps to make sure the idea is applicable to the entire community and not just the author. The ideal place to vet ideas is in the GitHub Discussions "Ideas" category (https://github.com/hashgraph/hedera-improvement-proposal/discussions/categories/ideas). +Vetting an idea publicly before writing a HIP is meant to save the potential author time. Asking the community first if an idea is original helps avoid spending too much time on something that may be rejected based on prior discussions. It also helps to make sure the idea is applicable to the entire community and not just the author. The ideal place to vet ideas is in the GitHub Discussions "Ideas" category (https://github.com/hashgraph/hedera-improvement-proposal/discussions/categories/ideas). Authors should: @@ -67,9 +71,9 @@ Authors should: 3. Fill out as much of the HIP template as the initial discussion comment. 4. Update the initial comment with any updates that have received consensus. -The goal is that once the Idea has been fully vetted, it should be relatively trivial to submit a formal HIP. +The goal is that once the Idea has been fully vetted, submitting a formal HIP should be relatively trivial. -Once the champion has discovered with the Hedera community the acceptability of the idea, the proposal should be submitted as a draft HIP via a GitHub pull request. The draft must be written in HIP style as described below, else it will fail review immediately (although minor errors may be corrected by the editors). +Once the champion has discovered with the Hedera community the idea's acceptability, the proposal should be submitted as a draft HIP via a GitHub pull request. The draft must be written in HIP style as described below; otherwise, it will fail review immediately (although minor errors may be corrected by the editors). ### ⚠️ Setting up DCO @@ -89,17 +93,17 @@ If you have set everything up correctly, your PR will pass automatic DCO tests, The standard HIP workflow is: -* You, the HIP author, fork the HIP repository, and create a file named `hip-0000-my-feature.md` (where "my-feature" is descriptive) that contains your new HIP. Use 0000 as your draft HIP number. This file should be created from the HIP template. +* You, the HIP author, fork the HIP repository and create a file named `hip-0000-my-feature.md` (where "my-feature" is descriptive) that contains your new HIP. Use 0000 as your draft HIP number. This file should be created from the HIP template. -* In the "Type" header field, enter "Standards Track", "Informational", or "Process" as appropriate. +* In the "Type" header field, enter "Standards Track," "Informational," or "Process" as appropriate. -* For "Status" field, enter "Draft." +* For the "Status" field, enter `Draft.` -* Push this to your Github fork and submit a draft pull request ([https://github.blog/2019-02-14-introducing-draft-pull-requests/](https://github.blog/2019-02-14-introducing-draft-pull-requests/)). +* Push this to your GitHub fork and submit a draft pull request ([https://github.blog/2019-02-14-introducing-draft-pull-requests/](https://github.blog/2019-02-14-introducing-draft-pull-requests/)). -* As you iterate through the community feedback, you add changes to the HIP which will be reflected in the draft pull request. +* As you iterate through the community feedback, you add changes to the HIP, which will be reflected in the draft pull request. -* Once you finalize the changes related to the feedback, convert the pull request from "Draft" to "Review". This will signal an editor to review your HIP. +* Once you finalize the changes related to the feedback, convert the pull request from `Draft` to `Review.` This will signal an editor to review your HIP. * The HIP editors review your PR for structure, formatting, and other errors. Approval criteria are: @@ -109,13 +113,13 @@ The standard HIP workflow is: * The HIP's language (spelling, grammar, sentence structure, etc.) and code style should be correct and conformant. - Editors are generally quite lenient about this initial review, expecting that problems will be corrected by the reviewing process. + Editors are generally quite lenient about this initial review, expecting that the reviewing process will correct problems. - If the HIP isn't ready for approval, an editor will send it back to the author for revision, with specific instructions and will change the status of the HIP back to the "Draft". + If the HIP isn't ready for approval, an editor will send it back to the author for revision with specific instructions and change its status to "Draft." -* Once approved, editors will assign your HIP a number, change status to "Draft" and merge your PR into the main branch. +* Once approved, editors will assign your HIP a number, change the status to "Draft," and merge your PR into the main branch. -HIP editors will not unreasonably deny publication of a HIP. Reasons for denying HIP status include duplication of effort, being technically unsound, or not providing proper motivation. +HIP editors will not unreasonably deny the publication of a HIP. Reasons for denying HIP status include duplication of effort, being technically unsound, or not providing proper motivation. Developers with git push privileges for the HIP repository may claim HIP numbers directly by creating and committing a new HIP. When doing so, the developer must handle the tasks that would normally be taken care of by the HIP editors. This includes ensuring the initial version meets the expected standards for submitting a HIP. Alternatively, even developers should submit HIPs via pull request. @@ -125,31 +129,31 @@ HIP authors are responsible for collecting community feedback on a HIP before su ### HIP Review & Resolution -Once authors have completed a HIP, they may request a review for style and consistency from the HIP editors. They can signal this by changing the status of the HIP in the HIP header from "Draft" to "Review." +Once authors have completed a HIP, they may request a style and consistency review from the HIP editors. They can signal this by changing the status of the HIP in the HIP header from `Draft` to `Review.` However, content review and final acceptance of the HIP must be requested of the core developers, which may include community developers responsible for the codebase being proposed for improvement. -For a HIP to be accepted, it must meet certain minimum criteria. It must be a clear and complete description of the proposed improvement. The improvement must represent a net value-add. The proposed implementation, if applicable, must be solid and must not complicate the network unduly. +For a HIP to be accepted, it must meet certain minimum criteria. It must be a clear and complete description of the proposed improvement, which must represent a net value-add. The proposed implementation, if applicable, must be solid and not unduly complicate the network. -To allow gathering of additional design and interface feedback before committing to long term stability, a HIP will be marked as "Last Call". This indicates that the proposal has been accepted for inclusion, but additional user feedback is needed before the full design can be considered "Accepted". A HIP in the "Last Call" status may still be Rejected or Withdrawn even after the related changes have been implemented. +A HIP will be marked as a `Last Call` to allow additional design and interface feedback to be gathered before committing to long-term stability. This indicates that the proposal has been accepted for inclusion, but additional user feedback is needed before the full design can be considered `Accepted.` A HIP in the `Last Call` status may still be `Rejected` or `Withheld` even after the related changes have been implemented. -This "Last Call" status stays in effect until the DateTime specified in `last-call-date-time` preamble field. This field is specified by the editor and is usually set as 14 days from the moment a pull requested is reviewed. +This `Last Call` status stays in effect until the `DateTime` specified in the `last-call-date-time` preamble field. The editor specifies this field and usually sets it to 14 days from the moment a pull request is reviewed. -An accepted HIP is a HIP that went through the "Last Call" period without changes and its status has been converted to "Accepted" by an editor at the end of `last-call-date-time` period. +An accepted HIP is one that went through the `Last Call` period without changes and whose status was converted to `Accepted` by an editor at the end of the `last-call-date-time` period. -Once a HIP has been accepted, the reference implementation must be completed. When the reference implementation is complete and incorporated into the main source code repository, the status will be changed to "Final". A Standards Track HIP must include a specification, and a reference implementation in order to be considered for a "Final" status. For Process HIPs and Standards Track HIPs that introduce protocol standards, once the process or protocol has been implemented and recognized as official by a combination of the community, core developers, and the Council, the status will be changed to "Final". +Once a HIP has been accepted, the reference implementation must be completed. When the reference implementation is complete and incorporated into the main source code repository, the status will be changed to `Final.` A Standards Track HIP must include a specification and a reference implementation in order to be considered for a `Final` status. For Process HIPs and Standards Track HIPs that introduce protocol standards, once the process or protocol has been implemented and recognized as official by a combination of the community, core developers, and the Council, the status will be changed to `Final.` -A HIP can also be assigned the status of "Deferred". The HIP author, or an editor can assign the HIP this status when no progress is being made on the HIP. Once a HIP is deferred, a HIP editor can re-assign to draft status. +A HIP can also be assigned the status of `Deferred.` The HIP author or an editor can assign this status when no progress is being made on the HIP. Once a HIP is deferred, an editor can re-assign it to draft status. -A HIP can also be "Rejected." Perhaps, after all is said and done, it was not a good idea. It is still important to have a record of this fact. The "Withdrawn" status is similar - it means that the HIP author themselves has decided that the HIP is actually a bad idea, or has accepted that a competing proposal is a better alternative. +A HIP can also be `Rejected.` Perhaps, after all is said and done, it was not a good idea. It is still important to have a record of this fact. The `Withdrawn` status is similar - it means that the HIP authors themselves have decided that the HIP is actually a bad idea or have accepted that a competing proposal is a better alternative. -When a HIP is Accepted, Rejected or Withdrawn, the HIP should be updated accordingly. +When a HIP is `Accepted,` `Rejected,` or `Withdrawn,` it should be updated accordingly. HIPs can also be superseded by a different HIP, rendering the original obsolete. This is intended for Informational HIPs, where version 2 of an API can replace version 1. -Some HIPs will have to be approved by the Governing Council before getting a `Accepted` status'. This is usually the case for HIPs in the `Standards Track` type and `Core`, `Service` and `Mirror` categories, but can expand to other HIPs as well. The HIPs editors will double-check if the `Yes` flag on `needs-council-approval` header field needs to be set. If HIP needs Governing Council approval, it will have to go through a 'Council Review' status and be reviewed at the next Technical Committee meeting of the Governing Council. +Some HIPs will have to be approved by the Governing Council before getting a `Accepted` status'. This is usually the case for HIPs in the `Standards Track` type and `Core`, `Service` and `Mirror` categories, but can expand to other HIPs as well. The HIPs editors will double-check if the `Yes` flag on the `needs-council-approval` header field needs to be set. If HIP needs Governing Council approval, it will have to go through a `Council Review` status and be reviewed at the next Technical Committee meeting of the Governing Council. -The Council (specifically techcom) approves the HIPs that have `needs-council-approval` field set to `yes`. The Council approves (if the HIP has reached the Council approval stage) or conditionally approves (if the HIP is still waiting in the public commenting phase) the HIPs. When a HIP goes through this approval, it may or may not have final state of the API defined. In this sense, the Council is voting on approving the feature for further design at that stage. +The Council (specifically TechComm) approves the HIPs with the `needs-council-approval` field set to `yes`. The Council approves (if the HIP has reached the Council approval stage) or conditionally approves (if the HIP is still waiting in the public commenting phase) the HIPs. When a HIP goes through this approval, it may or may not have the final state of the API defined. In this sense, the Council is voting on approving the feature for further design at that stage. After the Council approves the HIP, the HIP authors can add more details (like a more detailed API definition) to the HIP before it is implemented/active. Adding these details does not require re-approval from the Council. However, if the HIP deviates from its core design, it requires re-approval from the Council. @@ -164,10 +168,10 @@ The possible paths of the status of HIPs are as follows: - __Review__ - A HIP Author marks a HIP as ready for and requesting Editorial Review. - __Deferred__ - A HIP under consideration for future implementation, but not set for immediate action. - __Withdrawn__ - The HIP Author(s) have withdrawn the proposed HIP. This state has finality and can no longer be resurrected using this HIP number. If the idea is pursued at a later date - it is considered a new proposal. -- __Stagnant__ - Any HIP in Draft or Review if inactive for a period of 6 months or greater, is moved to Stagnant. A HIP may be resurrected from this state by Authors or HIP Editors through moving it back to Draft. -- __Rejected__ - Throughout the discussion of a HIP, various ideas will be proposed which are not accepted. Those rejected ideas should be recorded along with the reasoning as to why they were rejected. This helps record the thought process behind the final version of the HIP and prevents people from bringing up the same rejected idea again in subsequent discussions. -- __Last Call__ - This is the final review window for a HIP before moving to "Accepted." A HIP editor will assign Last Call status and set a review end date (`last-call-date-time`), typically 14 days later. If this period results in necessary normative changes, it will revert the HIP to Review. -- __Council Review__ - Some HIPs will have to be approved by the Governing Council before getting a `Accepted` status'. This is usually the case for HIPs in the `Standards Track` type and `Core`, `Service` and `Mirror` categories, but can expand to other HIPs as well. The HIP editors will double-check if the `Yes` flag on `needs-council-approval` header field needs to be set. If HIP needs Governing Council approval, it will have to go through a 'Council Review' status and be reviewed at the next Technical Committee meeting of the Governing Council. +- __Stagnant__ - Any HIP in `Draft` or `Review,` if inactive for a period of 6 months or greater, is moved to Stagnant. A HIP may be resurrected from this state by Authors or HIP Editors by moving it back to Draft. +- __Rejected__ - Throughout the discussion of a HIP, various ideas will be proposed that are not accepted. Those rejected ideas should be recorded along with the reasoning as to why they were rejected. This helps record the thought process behind the final version of the HIP and prevents people from bringing up the same rejected idea again in subsequent discussions. +- __Last Call__ - This is the final review window for a HIP before moving to "Accepted." A HIP editor will assign the `Last Call` status and set a review end date (`last-call-date-time`), typically 14 days later. If this period results in necessary normative changes, it will revert the HIP to Review. +- __Council Review__ - Some HIPs will have to be approved by the Governing Council before getting an `Accepted` status. This is usually the case for HIPs in the `Standards Track` type and `Core`, `Service` and `Mirror` categories, but can expand to other HIPs as well. The HIP editors will double-check if the `Yes` flag on the `needs-council-approval` header field needs to be set. If HIP needs Governing Council approval, it will have to go through a 'Council Review' status and be reviewed at the next Technical Committee meeting of the Governing Council. - __Accepted__ - An accepted HIP is a HIP that went through the "Last Call" status period without changes to the content and is considered ready for implementation. This is often a base HIP proposal for the development team to start implementing IP in code. - __Final__ - This HIP represents the final standard implemented in code. A Final HIP exists in a state of finality and should only be updated to correct errata and add non-normative clarifications. - __Active__ - Some Informational or Process HIPs may also have a status of "Active" if they are never meant to be completed. An "Active" HIP may be "Withdrawn" or "Replaced" by another HIP. If the idea is pursued at a later date - it is considered a new proposal. @@ -175,9 +179,9 @@ The possible paths of the status of HIPs are as follows: ### HIP Maintenance -In general, Standards track HIPs are no longer modified after they have reached the Final state. Once a HIP has been completed, the Hedera codebase becomes the formal documentation of the expected behavior. +In general, Standards track HIPs are no longer modified after they have reached the `Final` state. Once a HIP has been completed, the Hedera codebase becomes the formal documentation of the expected behavior. -If changes based on implementation experience and user feedback are made to Standards track HIPs while in Accepted state, those changes should be noted in the HIP, such that the HIP accurately describes the state of the implementation at the point where it is marked Final. +If changes based on implementation experience and user feedback are made to Standards track HIPs while in the `Accepted` state, those changes should be noted in the HIP, such that the HIP accurately describes the state of the implementation at the point where it is marked Final. Informational and Process HIPs may be updated over time to reflect changes to the development practices and other details. The precise process followed in these cases will depend on the nature and purpose of the HIP being updated. @@ -185,35 +189,35 @@ Informational and Process HIPs may be updated over time to reflect changes to th Each HIP should have the following parts/sections: -1. Preamble -- RFC 822 style headers containing meta-data about the HIP, including the HIP number, a short descriptive title (limited to a maximum of 44 characters), the names and, optionally, the contact info for each author, etc. The header items each should start with a new line and be wrapped in `---` symbols to format the preamble as a table and allow static site generators such as Jekyll use it as parameters for the page generation. +1. Preamble -- RFC 822 style headers containing meta-data about the HIP, including the HIP number, a short descriptive title (limited to a maximum of 44 characters), the names, and, optionally, the contact info for each author, etc. The header items each should start with a new line and be wrapped in `---` symbols to format the preamble as a table and allow static site generators such as Jekyll to use it as parameters for the page generation. 2. Abstract -- a short (~200 word) description of the technical issue being addressed. -3. Motivation -- The motivation is critical for HIPs that want to change the Hedera codebase or ecosystem. It should clearly explain why the existing specification is inadequate to address the problem that the HIP solves. HIP submissions without sufficient motivation may be rejected outright. +3. Motivation -- motivation is critical for HIPs that want to change the Hedera codebase or ecosystem. It should clearly explain why the existing specification is inadequate to address the problem that the HIP solves. HIP submissions without sufficient motivation may be rejected outright. 4. Rationale -- The rationale fleshes out the specification by describing 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 should provide evidence of consensus within the community and discuss important objections or concerns raised during the discussion. -5. User stories -- Provide a list of "user stories" to express how this feature, functionality, improvement, or tool will be used by the end user. Template for user story: "As (user persona), I want (to perform this action) so that (I can accomplish this goal)." +5. User stories -- Provide a list of "user stories" to express how the end user will use this feature, functionality, improvement, or tool. Template for user story: "As (user persona), I want (to perform this action) so that (I can accomplish this goal)." 6. Specification -- The technical specification should describe the syntax and semantics of any new features. The specification should be detailed enough to allow competing, interoperable implementations for at least the current Hedera ecosystem. 7. Backwards Compatibility -- All HIPs that introduce backward incompatibilities must include a section describing these incompatibilities and their severity. The HIP must explain how the author proposes to deal with these incompatibilities. HIP submissions without a sufficient backward compatibility treatise may be rejected outright. -8. Security Implications -- If there are security concerns in relation to the HIP, those concerns should be explicitly addressed to make sure reviewers of the HIP are aware of them. +8. Security Implications -- If there are security concerns related to the HIP, those concerns should be explicitly addressed to ensure that the HIP's reviewers are aware of them. -9. How to Teach This -- For a HIP that adds new functionality or changes interface behaviors, it is helpful to include a section on how to teach users, new and experienced, how to apply the HIP to their work. +9. How to Teach This -- For a HIP that adds new functionality or changes interface behaviors, it is helpful to include a section on how to teach new and experienced users how to apply the HIP to their work. -10. Reference Implementation -- The reference implementation must be complete before any HIP is given the status of "Final". The final implementation must include test code and documentation. +10. Reference Implementation -- The reference implementation must be complete before any HIP is given the status of `Final`. The final implementation must include test code and documentation. -11. Rejected Ideas -- Throughout the discussion of a HIP, various ideas will be proposed which are not accepted. Those rejected ideas should be recorded along with the reasoning as to why they were rejected. This both helps record the thought process behind the final version of the HIP as well as preventing people from bringing up the same rejected idea again in subsequent discussions. +11. Rejected Ideas -- Throughout the discussion of a HIP, various ideas will be proposed that are not accepted. Those rejected ideas should be recorded along with the reasoning behind their rejection. This helps record the thought process behind the final version of the HIP and prevents people from bringing up the same rejected idea again in subsequent discussions. In a way, this section can be thought of as a breakout section of the Rationale section that focuses specifically on why certain ideas were not ultimately pursued. -12. Open Issues -- While a HIP is in draft, ideas can come up which warrant further discussion. Those ideas should be recorded so people know that they are being thought about but do not have a concrete resolution. This helps make sure all issues required for the HIP to be ready for consideration are complete and reduces people duplicating prior discussions. +12. Open Issues -- While a HIP is in draft, ideas can come up that warrant further discussion. Those ideas should be recorded so people know that they are being thought about but do not have a concrete resolution. This helps make sure all issues required for the HIP to be ready for consideration are complete and reduces people duplicating prior discussions. -13. References -- A collections of URLs used as references through the HIP. +13. References -- A collection of URLs used as references through the HIP. 14. Copyright/license -- Each new HIP must be placed under the Apache License, Version 2.0 -- see [LICENSE](../LICENSE) or (https://www.apache.org/licenses/LICENSE-2.0) @@ -259,7 +263,7 @@ Random J. User (@username) if the email address or GitHub username is included, and Random J. User -if email or username are not given. +if email or username is not given. It is not possible to use both an email and a GitHub username at the same time. If important to include both, one could include their name twice, once with the GitHub username and once with the email. @@ -303,11 +307,11 @@ The category header specifies the HIP category (Core, Service, API, Mirror, Appl #### `needs-council-approval` header -This field specifies if the HIP needs to be reviewed and approved by the Hedera Council Technical Committee before getting a `Accepted` status'. This is usually the case for HIPs in the `Standards Track` type and `Core`, `Service` and `Mirror` categories, but can expand to other HIPs as well. The HIP author should set it based on their judgement of whether the HIP modifies any of the Hedera Core, Service or Mirror code, but the HIPs editors will double-check if the `Yes` flag needs to be set. +This field specifies if the HIP needs to be reviewed and approved by the Hedera Council Technical Committee before getting a `Accepted` status'. This is usually the case for HIPs in the `Standards Track` type and `Core`, `Service` and `Mirror` categories, but can expand to other HIPs as well. The HIP author should set it based on their judgment of whether the HIP modifies any of the Hedera Core, Service or Mirror code, but the HIP's editors will double-check if the `Yes` flag needs to be set. #### `created` header -The created header records the date that the HIP was assigned a number. This header should be in ISO 8601 format (yyyy-mm-dd), e.g. 2019-09-16. +The `created` header records the date that the HIP was assigned a number. This header should be in ISO 8601 format (yyyy-mm-dd), e.g. 2019-09-16. #### `last-call-date-time` header @@ -315,19 +319,19 @@ The anticipated date and time when this HIP will change status to `Accepted`. Th #### `updated` header -The updated header records the date(s) when the HIP was updated with "substantial" changes. The header is only valid for HIPs of Draft and Active status. This header should be in ISO 8601 format (yyyy-mm-dd), e.g. 2019-09-16. +The updated header records the date(s) when the HIP was updated with "substantial" changes. It is only valid for HIPs in `Draft` and `Active` status. This header should be in ISO 8601 format (yyyy-mm-dd), e.g., 2019-09-16. #### `requires` header -HIPs may have a requires header, indicating the HIP numbers that this HIP depends on. +HIPs may have a `requires` header, indicating the HIP numbers that this HIP depends on. #### `superseded-by` and `replaces` headers -HIPs may also have a superseded-by header indicating that a HIP has been rendered obsolete by a later document; the value is the number of the HIP that replaces the current document. The current document must change status to "Replaced" once the superseding HIP is changed to "Final" status. The newer HIP must have a replaces header containing the number of the HIP that it rendered obsolete. +HIPs may also have a `superseded-by` header indicating that a HIP has been rendered obsolete by a later document; the value is the number of the HIP that replaces the current document. The current document must change status to `Replaced` once the superseding HIP is changed to `Final` status. The newer HIP must have a `replaces` header containing the number of the HIP that it rendered obsolete. #### `release` header -The release header indicates when the HIP was implemented on the network (vX.Y.Z), e.g. 0.29.0. +The `release` header indicates when the HIP was implemented on the network (vX.Y.Z), e.g. `0.29.0`. ### Linking to other HIPs @@ -335,11 +339,11 @@ References to other HIPs should follow the format HIP-N where N is the HIP numbe ### Auxiliary Files -Images, diagrams, and auxiliary files should be included in a subdirectory of the assets folder for that HIP as follows: assets/hip-N (where N is to be replaced with the HIP number). When linking to an image in the HIP, use relative links such as `../assets/hip-1/image.png`. +Images, diagrams, and auxiliary files should be included in a subdirectory of the assets folder for that HIP, such as `assets/hip-N` (where N is to be replaced with the HIP number). When linking to an image in the HIP, use relative links such as `../assets/hip-1/image.png`. ## Reporting HIP Bugs, or Submitting HIP Updates -How you report a bug, or submit a HIP update depends on several factors, such as the maturity of the HIP, the preferences of the HIP author, and the nature of your comments. For early draft stages of the HIP, it's probably best to send your comments and changes directly to the HIP author. For more mature, or finished HIPs you may want to submit corrections as a GitHub issue or GitHub pull request so that your changes don't get lost. +How you report a bug or submit a HIP update depends on several factors, such as the maturity of the HIP, the preferences of the HIP author, and the nature of your comments. For the early draft stages of the HIP, it's probably best to send your comments and changes directly to the HIP author. For more mature or finished HIPs, you may want to submit corrections as a GitHub issue or GitHub pull request so that your changes don't get lost. When in doubt about where to send your changes, please check first with the HIP author and/or a HIP editor. @@ -355,7 +359,7 @@ For each new HIP that comes in, an editor does the following: - Read the HIP 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 Final status. - The title should accurately describe the content. -- Check the HIP for language (spelling, grammar, sentence structure, etc.), markup (GitHub flavored Markdown), and code style. +- Check the HIP for language (spelling, grammar, sentence structure, etc.), markup (GitHub-flavored Markdown), and code style. If the HIP isn't ready, the editor will send it back to the author for revision with specific instructions. @@ -364,7 +368,7 @@ For each new HIP that comes in, an editor does the following: - Merge the corresponding pull request - Send a message back to the HIP author with the next step. -Editors don't pass judgement on the HIPs. We merely do the administrative & editorial part. +Editors don't pass judgment on the HIPs. We merely do the administrative & editorial part. ## Style Guide From f98e66f0bddf22456fc6a2e193dec29b24414081 Mon Sep 17 00:00:00 2001 From: Michael Garber Date: Tue, 22 Oct 2024 16:34:16 -0400 Subject: [PATCH 2/2] Update hip-1.md to reflect Hiero process Signed-off-by: Michael Garber --- HIP/hip-1.md | 149 +++++++++++++++++++++++++-------------------------- 1 file changed, 74 insertions(+), 75 deletions(-) diff --git a/HIP/hip-1.md b/HIP/hip-1.md index 9e289cdb6..d6cbcc260 100644 --- a/HIP/hip-1.md +++ b/HIP/hip-1.md @@ -3,7 +3,7 @@ hip: 1 title: Hedera Improvement Proposal Process author: Ken Anderson (@kenthejr), Serg Metelin (@sergmetelin), Simi Hunjan (@SimiHunjan), Michael Garber (@mgarbs) type: Process -needs-council-approval: No +needs-tsc-approval: No status: Active created: 2021-02-11 discussions-to: https://github.com/hashgraph/hedera-improvement-proposal/discussions/54 @@ -25,28 +25,24 @@ HIPs are not meant to address bugs in implemented code. Bugs should be addressed There are three kinds of HIP: 1. A **Standards Track** HIP describes a new feature or implementation for Hedera. It may also describe an interoperability standard that will be supported outside of the official Hedera node software stack. The Standards Track HIP abstract should include which part of the Hedera ecosystem it addresses. Standards Track HIPs require a specification and a reference implementation: - **a. Core:** This includes proposals addressing the Hashgraph algorithm, peer-to-peer networking, and other features implemented on Hedera consensus nodes. - **b. Service:** Hedera services sit on top of the Core node software and provide the functionalities that users access. These currently include the File Service, Consensus Service, Token Service, and Smart Contract Service. This type of proposal should be used to add to or improve Hedera's service layer. These features are implemented on Hedera consensus nodes. - **c. Mirror:** A mirror node runs software designed to retrieve all or some of the records generated by the Hedera consensus nodes and make those records available to users in a way that is meaningful, reliable, and trustworthy. - **d. Application:** Application standards may be used to standardize software in the Hedera ecosystem that does not affect Mirror or Consensus nodes. This includes application network software, external contract consensus nodes, multi-sig oracles, persistence mechanisms, enterprise software plugins, etc. An example of an Application standard would be the Stablecoin Contract and Non-fungible Token Contract written in Java as a layer-2 solution using the Hedera Consensus service to maintain trust. 2. An **Informational** HIP describes a Hedera design issue or provides general guidelines or information to the Hedera community but does not propose a new feature. Informational HIPs do not necessarily represent a Hedera community consensus or recommendation, so users and implementers are free to ignore Informational HIPs or follow their directions. -3. A **Process** HIP describes a process surrounding Hedera or proposes a change to a process. Process HIPs are like Standards Track HIPs but apply to areas other than the node and ecosystem software codebases. They may propose an implementation, but not to Hedera's codebase; they often require community consensus; unlike Informational HIPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, and changes to the decision-making process. Any meta-HIP is also considered a Process HIP. +3. A **Process** HIP describes a process surrounding Hedera or proposes a change to a process. Process HIPs are like Standards Track HIPs but apply to areas other than the node and ecosystem software codebases. They may propose an implementation but not to Hiero's codebase; they often require community consensus; unlike Informational HIPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, and changes to the decision-making process. Any meta-HIP is also considered a Process HIP. ## HIP Workflow ### Hiero Technical Steering Committee -The Technical Steering Committee (the “Hiero TSC”) is responsible for all technical oversight of the Hiero codebase. It has the final say on Core, Service, and Mirror node Standards Track HIPs, as well as Process HIPs. You can read more about Hiero and Hiero TSC here: https://github.com/hiero-ledger/hiero/blob/main/technical-charter.md +The Hiero Technical Steering Committee (the “Hiero TSC”) is responsible for all technical oversight of the Hiero codebase. It has the final say on whether a HIP is accepted into the codebase. You can read more about Hiero and the Hiero TSC here: [Hiero Technical Charter](https://github.com/hiero-ledger/hiero/blob/main/technical-charter.md). -### Hedera Council Technical Committee +### Hedera Governing Council -The Hedera Council, or "the Council," is made up of large organizations that participate in decisions related to the technical development roadmap, treasury management, and general governance. Its Technical Committee (Hedera TechComm) is composed of technical representation of Governing Council members and has the final say on what HIPs will be integrated into the Hedera public network. +The Hedera Governing Council runs the Hedera mainnet and has the final say on whether any Hiero accepted HIP gets approved to be deployed on mainnet. ### Hedera Core Developers @@ -54,7 +50,7 @@ Hedera Core Developers or "core developers" include those who are tasked with th ### HIP Editors -The HIP editors or "editors" are individuals responsible for managing the administrative and editorial aspects of the HIP workflow. HIP editorship is by invitation of the current editors or by assignment by the Council. +The HIP editors or "editors" are individuals responsible for managing the administrative and editorial aspects of the HIP workflow. HIP editorship is by invitation of the current editors or by assignment by the Hiero TSC. ### Start with an idea for Hedera @@ -93,31 +89,31 @@ If you have set everything up correctly, your PR will pass automatic DCO tests, The standard HIP workflow is: -* You, the HIP author, fork the HIP repository and create a file named `hip-0000-my-feature.md` (where "my-feature" is descriptive) that contains your new HIP. Use 0000 as your draft HIP number. This file should be created from the HIP template. +- You, the HIP author, fork the HIP repository and create a file named `hip-0000-my-feature.md` (where "my-feature" is descriptive) that contains your new HIP. Use 0000 as your draft HIP number. This file should be created from the HIP template. -* In the "Type" header field, enter "Standards Track," "Informational," or "Process" as appropriate. - -* For the "Status" field, enter `Draft.` +- In the "Type" header field, enter "Standards Track," "Informational," or "Process" as appropriate. -* Push this to your GitHub fork and submit a draft pull request ([https://github.blog/2019-02-14-introducing-draft-pull-requests/](https://github.blog/2019-02-14-introducing-draft-pull-requests/)). +- For the "Status" field, enter `Draft.` -* As you iterate through the community feedback, you add changes to the HIP, which will be reflected in the draft pull request. +- Push this to your GitHub fork and submit a draft pull request ([https://github.blog/2019-02-14-introducing-draft-pull-requests/](https://github.blog/2019-02-14-introducing-draft-pull-requests/)). -* Once you finalize the changes related to the feedback, convert the pull request from `Draft` to `Review.` This will signal an editor to review your HIP. +- As you iterate through the community feedback, you add changes to the HIP, which will be reflected in the draft pull request. -* The HIP editors review your PR for structure, formatting, and other errors. Approval criteria are: +- Once you finalize the changes related to the feedback, convert the pull request from `Draft` to `Review.` This will signal an editor to review your HIP. - * It is sound and complete. The ideas must make technical sense. The editors do not consider whether they seem likely to be accepted. +- The HIP editors review your PR for structure, formatting, and other errors. Approval criteria are: - * The title accurately describes the content. + - It is sound and complete. The ideas must make technical sense. The editors do not consider whether they seem likely to be accepted. - * The HIP's language (spelling, grammar, sentence structure, etc.) and code style should be correct and conformant. + - The title accurately describes the content. + + - The HIP's language (spelling, grammar, sentence structure, etc.) and code style should be correct and conformant. Editors are generally quite lenient about this initial review, expecting that the reviewing process will correct problems. If the HIP isn't ready for approval, an editor will send it back to the author for revision with specific instructions and change its status to "Draft." -* Once approved, editors will assign your HIP a number, change the status to "Draft," and merge your PR into the main branch. +- Once approved, editors will assign your HIP a number, change the status to "Draft," and merge your PR into the main branch. HIP editors will not unreasonably deny the publication of a HIP. Reasons for denying HIP status include duplication of effort, being technically unsound, or not providing proper motivation. @@ -135,13 +131,13 @@ However, content review and final acceptance of the HIP must be requested of the For a HIP to be accepted, it must meet certain minimum criteria. It must be a clear and complete description of the proposed improvement, which must represent a net value-add. The proposed implementation, if applicable, must be solid and not unduly complicate the network. -A HIP will be marked as a `Last Call` to allow additional design and interface feedback to be gathered before committing to long-term stability. This indicates that the proposal has been accepted for inclusion, but additional user feedback is needed before the full design can be considered `Accepted.` A HIP in the `Last Call` status may still be `Rejected` or `Withheld` even after the related changes have been implemented. +A HIP will be marked as a `Last Call` to allow additional design and interface feedback to be gathered before committing to long-term stability. This indicates that the proposal has been accepted for inclusion, but additional user feedback is needed before the full design can be considered `Accepted.` A HIP in the `Last Call` status may still be `Rejected` or `Withdrawn` even after the related changes have been implemented. This `Last Call` status stays in effect until the `DateTime` specified in the `last-call-date-time` preamble field. The editor specifies this field and usually sets it to 14 days from the moment a pull request is reviewed. An accepted HIP is one that went through the `Last Call` period without changes and whose status was converted to `Accepted` by an editor at the end of the `last-call-date-time` period. -Once a HIP has been accepted, the reference implementation must be completed. When the reference implementation is complete and incorporated into the main source code repository, the status will be changed to `Final.` A Standards Track HIP must include a specification and a reference implementation in order to be considered for a `Final` status. For Process HIPs and Standards Track HIPs that introduce protocol standards, once the process or protocol has been implemented and recognized as official by a combination of the community, core developers, and the Council, the status will be changed to `Final.` +Once a Standards Track HIP has been `Accepted` by the Hiero TSC, the reference implementation must be completed. When the reference implementation is complete and incorporated into the main source code repository, the status will be changed to `Final.` A Standards Track HIP must include a specification and a reference implementation in order to be considered for a `Final` status. A HIP can also be assigned the status of `Deferred.` The HIP author or an editor can assign this status when no progress is being made on the HIP. Once a HIP is deferred, an editor can re-assign it to draft status. @@ -151,11 +147,11 @@ When a HIP is `Accepted,` `Rejected,` or `Withdrawn,` it should be updated accor HIPs can also be superseded by a different HIP, rendering the original obsolete. This is intended for Informational HIPs, where version 2 of an API can replace version 1. -Some HIPs will have to be approved by the Governing Council before getting a `Accepted` status'. This is usually the case for HIPs in the `Standards Track` type and `Core`, `Service` and `Mirror` categories, but can expand to other HIPs as well. The HIPs editors will double-check if the `Yes` flag on the `needs-council-approval` header field needs to be set. If HIP needs Governing Council approval, it will have to go through a `Council Review` status and be reviewed at the next Technical Committee meeting of the Governing Council. +Some HIPs will have to be reviewed by the Hiero Technical Steering Committee (TSC) before getting an `Accepted` status. This is usually the case for HIPs in the `Standards Track` type and `Core`, `Service`, and `Mirror` categories, but can expand to other HIPs as well, including `Process` HIPs. The HIP editors will double-check if the `Yes` flag on the `needs-tsc-approval` header field needs to be set. If a HIP needs TSC approval, it will have to go through a `TSC Review` status and be reviewed by the Hiero TSC. -The Council (specifically TechComm) approves the HIPs with the `needs-council-approval` field set to `yes`. The Council approves (if the HIP has reached the Council approval stage) or conditionally approves (if the HIP is still waiting in the public commenting phase) the HIPs. When a HIP goes through this approval, it may or may not have the final state of the API defined. In this sense, the Council is voting on approving the feature for further design at that stage. +The Hiero TSC reviews and accepts HIPs for inclusion into the codebase. The TSC ensures that the HIP aligns with the project's technical goals and standards. -After the Council approves the HIP, the HIP authors can add more details (like a more detailed API definition) to the HIP before it is implemented/active. Adding these details does not require re-approval from the Council. However, if the HIP deviates from its core design, it requires re-approval from the Council. +After the TSC accepts the HIP, the HIP authors can add more details (like a more detailed API definition) to the HIP before it is implemented. Adding these details does not require re-approval from the TSC. However, if the HIP deviates from its core design, it requires re-approval from the TSC. The possible paths of the status of HIPs are as follows: @@ -163,63 +159,63 @@ The possible paths of the status of HIPs are as follows: ### HIP Status Titles -- __Idea__ - An idea that is pre-draft. This is not tracked within the HIP Repository. -- __Draft__ - The first formally tracked stage of a HIP in development. A HIP is merged by a HIP Editor into the HIP repository when properly formatted. -- __Review__ - A HIP Author marks a HIP as ready for and requesting Editorial Review. -- __Deferred__ - A HIP under consideration for future implementation, but not set for immediate action. -- __Withdrawn__ - The HIP Author(s) have withdrawn the proposed HIP. This state has finality and can no longer be resurrected using this HIP number. If the idea is pursued at a later date - it is considered a new proposal. -- __Stagnant__ - Any HIP in `Draft` or `Review,` if inactive for a period of 6 months or greater, is moved to Stagnant. A HIP may be resurrected from this state by Authors or HIP Editors by moving it back to Draft. -- __Rejected__ - Throughout the discussion of a HIP, various ideas will be proposed that are not accepted. Those rejected ideas should be recorded along with the reasoning as to why they were rejected. This helps record the thought process behind the final version of the HIP and prevents people from bringing up the same rejected idea again in subsequent discussions. -- __Last Call__ - This is the final review window for a HIP before moving to "Accepted." A HIP editor will assign the `Last Call` status and set a review end date (`last-call-date-time`), typically 14 days later. If this period results in necessary normative changes, it will revert the HIP to Review. -- __Council Review__ - Some HIPs will have to be approved by the Governing Council before getting an `Accepted` status. This is usually the case for HIPs in the `Standards Track` type and `Core`, `Service` and `Mirror` categories, but can expand to other HIPs as well. The HIP editors will double-check if the `Yes` flag on the `needs-council-approval` header field needs to be set. If HIP needs Governing Council approval, it will have to go through a 'Council Review' status and be reviewed at the next Technical Committee meeting of the Governing Council. -- __Accepted__ - An accepted HIP is a HIP that went through the "Last Call" status period without changes to the content and is considered ready for implementation. This is often a base HIP proposal for the development team to start implementing IP in code. -- __Final__ - This HIP represents the final standard implemented in code. A Final HIP exists in a state of finality and should only be updated to correct errata and add non-normative clarifications. -- __Active__ - Some Informational or Process HIPs may also have a status of "Active" if they are never meant to be completed. An "Active" HIP may be "Withdrawn" or "Replaced" by another HIP. If the idea is pursued at a later date - it is considered a new proposal. -- __Replaced__ - "Replaced" HIPs are overwritten by a newer standard or implementation. +- **Idea** - An idea that is pre-draft. This is not tracked within the HIP Repository. +- **Draft** - The first formally tracked stage of a HIP in development. A HIP is merged by a HIP Editor into the HIP repository when properly formatted. +- **Review** - A HIP Author marks a HIP as ready for and requesting Editorial Review. +- **Deferred** - A HIP under consideration for future implementation, but not set for immediate action. +- **Withdrawn** - The HIP Author(s) have withdrawn the proposed HIP. This state has finality and can no longer be resurrected using this HIP number. If the idea is pursued at a later date—it is considered a new proposal. +- **Stagnant** - Any HIP in `Draft` or `Review,` if inactive for a period of 6 months or greater, is moved to Stagnant. A HIP may be resurrected from this state by Authors or HIP Editors by moving it back to Draft. +- **Rejected** - Throughout the discussion of a HIP, various ideas will be proposed that are not accepted. Those rejected ideas should be recorded along with the reasoning as to why they were rejected. This helps record the thought process behind the final version of the HIP and prevents people from bringing up the same rejected idea again in subsequent discussions. +- **Last Call** - This is the final review window for a HIP before moving to "Accepted." A HIP editor will assign the `Last Call` status and set a review end date (`last-call-date-time`), typically 14 days later. If this period results in necessary normative changes, it will revert the HIP to Review. +- **TSC Review** - Some HIPs will have to be accepted by the Hiero Technical Steering Committee before getting an `Accepted` status. This is usually the case for HIPs in the `Standards Track` type and `Core`, `Service`, and `Mirror` categories, but can expand to other HIPs as well, including `Process` HIPs. +- **Accepted** - An accepted HIP is a HIP that went through the "Last Call" status period without changes to the content and is considered ready for implementation in the codebase. +- **Final** - This HIP represents the final standard implemented in code. A `Final` HIP exists in a state of finality and should only be updated to correct errata and add non-normative clarifications. +- **Active** - Some Informational or Process HIPs may also have a status of `Active` if they are never meant to be completed. An `Active` HIP may be `Withdrawn` or `Replaced` by another HIP. If the idea is pursued at a later date—it is considered a new proposal. +- **Replaced** - `Replaced` HIPs are overwritten by a newer standard or implementation. ### HIP Maintenance -In general, Standards track HIPs are no longer modified after they have reached the `Final` state. Once a HIP has been completed, the Hedera codebase becomes the formal documentation of the expected behavior. +In general, Standards Track HIPs are no longer modified after they have reached the `Final` state. Once a HIP has been completed, the Hiero codebase becomes the formal documentation of the expected behavior. -If changes based on implementation experience and user feedback are made to Standards track HIPs while in the `Accepted` state, those changes should be noted in the HIP, such that the HIP accurately describes the state of the implementation at the point where it is marked Final. +If changes based on implementation experience and user feedback are made to Standards Track HIPs while in the `Accepted` state, those changes should be noted in the HIP, such that the HIP accurately describes the state of the implementation at the point where it is marked `Final`. -Informational and Process HIPs may be updated over time to reflect changes to the development practices and other details. The precise process followed in these cases will depend on the nature and purpose of the HIP being updated. +Informational and Process HIPs may be updated over time to reflect changes to the development practices and other details. The precise process followed in these cases will depend on the nature and purpose of the HIP being updated. **Process HIP changes must be reviewed by the Hiero TSC in the same manner as Core, Service, and Mirror HIPs.** ## What belongs in a successful HIP? Each HIP should have the following parts/sections: -1. Preamble -- RFC 822 style headers containing meta-data about the HIP, including the HIP number, a short descriptive title (limited to a maximum of 44 characters), the names, and, optionally, the contact info for each author, etc. The header items each should start with a new line and be wrapped in `---` symbols to format the preamble as a table and allow static site generators such as Jekyll to use it as parameters for the page generation. +1. **Preamble**-RFC 822 style headers containing meta-data about the HIP, including the HIP number, a short descriptive title (limited to a maximum of 44 characters), the names, and, optionally, the contact info for each author, etc. The header items each should start with a new line and be wrapped in `---` symbols to format the preamble as a table and allow static site generators such as Jekyll to use it as parameters for the page generation. -2. Abstract -- a short (~200 word) description of the technical issue being addressed. +2. **Abstract**—a short (~200 word) description of the technical issue being addressed. -3. Motivation -- motivation is critical for HIPs that want to change the Hedera codebase or ecosystem. It should clearly explain why the existing specification is inadequate to address the problem that the HIP solves. HIP submissions without sufficient motivation may be rejected outright. +3. **Motivation**—motivation is critical for HIPs that want to change the Hedera codebase or ecosystem. It should clearly explain why the existing specification is inadequate to address the problem that the HIP solves. HIP submissions without sufficient motivation may be rejected outright. -4. Rationale -- The rationale fleshes out the specification by describing 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. +4. **Rationale**—The rationale fleshes out the specification by describing 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 should provide evidence of consensus within the community and discuss important objections or concerns raised during the discussion. + The rationale should provide evidence of consensus within the community and discuss important objections or concerns raised during the discussion. -5. User stories -- Provide a list of "user stories" to express how the end user will use this feature, functionality, improvement, or tool. Template for user story: "As (user persona), I want (to perform this action) so that (I can accomplish this goal)." +5. **User stories**—Provide a list of "user stories" to express how the end user will use this feature, functionality, improvement, or tool. Template for user story: "As (user persona), I want (to perform this action) so that (I can accomplish this goal)." -6. Specification -- The technical specification should describe the syntax and semantics of any new features. The specification should be detailed enough to allow competing, interoperable implementations for at least the current Hedera ecosystem. +6. **Specification**—The technical specification should describe the syntax and semantics of any new features. The specification should be detailed enough to allow competing, interoperable implementations for at least the current Hedera ecosystem. -7. Backwards Compatibility -- All HIPs that introduce backward incompatibilities must include a section describing these incompatibilities and their severity. The HIP must explain how the author proposes to deal with these incompatibilities. HIP submissions without a sufficient backward compatibility treatise may be rejected outright. +7. **Backwards Compatibility**—All HIPs that introduce backward incompatibilities must include a section describing these incompatibilities and their severity. The HIP must explain how the author proposes to deal with these incompatibilities. HIP submissions without a sufficient backward compatibility treatise may be rejected outright. -8. Security Implications -- If there are security concerns related to the HIP, those concerns should be explicitly addressed to ensure that the HIP's reviewers are aware of them. +8. **Security Implications**—If there are security concerns related to the HIP, those concerns should be explicitly addressed to ensure that the HIP's reviewers are aware of them. -9. How to Teach This -- For a HIP that adds new functionality or changes interface behaviors, it is helpful to include a section on how to teach new and experienced users how to apply the HIP to their work. +9. **How to Teach This**—For a HIP that adds new functionality or changes interface behaviors, it is helpful to include a section on how to teach new and experienced users how to apply the HIP to their work. -10. Reference Implementation -- The reference implementation must be complete before any HIP is given the status of `Final`. The final implementation must include test code and documentation. +10. **Reference Implementation**—The reference implementation must be complete before any HIP is given the status of `Final`. The final implementation must include test code and documentation. -11. Rejected Ideas -- Throughout the discussion of a HIP, various ideas will be proposed that are not accepted. Those rejected ideas should be recorded along with the reasoning behind their rejection. This helps record the thought process behind the final version of the HIP and prevents people from bringing up the same rejected idea again in subsequent discussions. +11. **Rejected Ideas**—Throughout the discussion of a HIP, various ideas will be proposed that are not accepted. Those rejected ideas should be recorded along with the reasoning behind their rejection. This helps record the thought process behind the final version of the HIP and prevents people from bringing up the same rejected idea again in subsequent discussions. In a way, this section can be thought of as a breakout section of the Rationale section that focuses specifically on why certain ideas were not ultimately pursued. -12. Open Issues -- While a HIP is in draft, ideas can come up that warrant further discussion. Those ideas should be recorded so people know that they are being thought about but do not have a concrete resolution. This helps make sure all issues required for the HIP to be ready for consideration are complete and reduces people duplicating prior discussions. +12. **Open Issues**—While a HIP is in draft, ideas can come up that warrant further discussion. Those ideas should be recorded so people know that they are being thought about but do not have a concrete resolution. This helps make sure all issues required for the HIP to be ready for consideration are complete and reduces people duplicating prior discussions. -13. References -- A collection of URLs used as references through the HIP. +13. **References**—A collection of URLs used as references through the HIP. -14. Copyright/license -- Each new HIP must be placed under the Apache License, Version 2.0 -- see [LICENSE](../LICENSE) or (https://www.apache.org/licenses/LICENSE-2.0) +14. **Copyright/license**—Each new HIP must be placed under the Apache License, Version 2.0—see [LICENSE](../LICENSE) or (https://www.apache.org/licenses/LICENSE-2.0) ## HIP Formats and Templates @@ -236,10 +232,10 @@ Each HIP must begin with a header preamble in a table format. The headers must a - requested-by: the name(s) and/or username(s), or name(s) and email(s) of the individual(s) or project(s) requesting the HIP - type: Standards Track | Informational | Process - category\*: Core | Service | API | Mirror | Application -- needs-council-approval: Yes | No -- status: Draft | Withdrawn | Review | Stagnant | Deferred | Last Call | Accepted | Rejected | Final | Active | Replaced +- needs-tsc-approval: Yes | No +- status: Draft | Withdrawn | Review | Stagnant | Deferred | Last Call | Accepted | Rejected | Final | Active | Replaced - created: date created on -- last-call-date-time: the anticipated date and time when this HIP will change status to `Last Call,` filled out by the editor +- last-call-date-time: the anticipated date and time when this HIP will change status to `Last Call`, filled out by the editor - discussions-to: a URL pointing to the official discussion thread - updated\*: comma-separated list of dates - requires\*: HIP number(s) @@ -271,9 +267,9 @@ At least one author must use a GitHub username in order to be notified on change #### `working-group` header -If the HIP includes multiple stakeholders, including technical and/or business stakeholders, that can address questions and discussions about the HIP, they should be listed in this section. +If the HIP includes multiple stakeholders, including technical and/or business stakeholders, that can address questions and discussions about the HIP, they should be listed in this section. -Those who prefer anonymity may use a username only, or a first name and a username. The format of the author header value must be: +Those who prefer anonymity may use a username only, or a first name and a username. The format of the `working-group` header value must be: Random J. User @@ -287,7 +283,7 @@ if email or username are not given. It is not possible to use both an email and a GitHub username at the same time. If important to include both, one could include their name twice, once with the GitHub username and once with the email. -At least one author must use a GitHub username in order to be notified on change requests and have the capability to approve or reject them. +At least one member must use a GitHub username in order to be notified on change requests and have the capability to approve or reject them. #### `discussions-to` header @@ -299,27 +295,29 @@ As a single exception, discussions-to cannot point to GitHub pull requests. #### `type` header -The Type header specifies the type of HIP: Standards Track, Informational, or Process. If the track is Standards, the HIP must include the category header. +The Type header specifies the type of HIP: Standards Track, Informational, or Process. If the type is Standards Track, the HIP must include the category header. #### `category` header -The category header specifies the HIP category (Core, Service, API, Mirror, Application). This is required for Standard Track HIPs only. +The category header specifies the HIP category (Core, Service, API, Mirror, Application). This is required for Standards Track HIPs only. -#### `needs-council-approval` header +#### `needs-tsc-approval` header -This field specifies if the HIP needs to be reviewed and approved by the Hedera Council Technical Committee before getting a `Accepted` status'. This is usually the case for HIPs in the `Standards Track` type and `Core`, `Service` and `Mirror` categories, but can expand to other HIPs as well. The HIP author should set it based on their judgment of whether the HIP modifies any of the Hedera Core, Service or Mirror code, but the HIP's editors will double-check if the `Yes` flag needs to be set. +This field specifies if the HIP needs to be reviewed and approved by the Hiero Technical Steering Committee before getting an `Accepted` status. This is usually the case for HIPs in the `Standards Track` type and `Core`, `Service`, and `Mirror` categories, but can expand to other HIPs as well, including `Process` HIPs. The HIP author should set it based on their judgment of whether the HIP modifies any of the Hedera Core, Service, or Mirror code, but the HIP editors will double-check if the `Yes` flag needs to be set. + +Note: This supercedes the old field `needs-council-approval`. While HIPs prior to Hiero migration maintain this old field for historical referencing; it is no longer used in new HIP headers. Hedera Governing Council TechComm maintains a separate decision-making process on which HIPs to integrate on the Hedera network. #### `created` header -The `created` header records the date that the HIP was assigned a number. This header should be in ISO 8601 format (yyyy-mm-dd), e.g. 2019-09-16. +The `created` header records the date that the HIP was assigned a number. This header should be in ISO 8601 format (`yyyy-mm-dd`), e.g., `2019-09-16`. #### `last-call-date-time` header -The anticipated date and time when this HIP will change status to `Accepted`. This header should be in ISO 8601 format expressed in UTC (yyyy-mm-ddThh:mm:ssZ), e.g. 2019-09-16T13:15:30Z. This field is usually set as 14 days from the moment a pull requested is reviewed. +The anticipated date and time when this HIP will change status to `Last Call`. This header should be in ISO 8601 format expressed in UTC (`yyyy-mm-ddThh:mm:ssZ`), e.g. `2019-09-16T13:15:30Z`. This field is usually set as 14 days from the moment a pull request is reviewed. #### `updated` header -The updated header records the date(s) when the HIP was updated with "substantial" changes. It is only valid for HIPs in `Draft` and `Active` status. This header should be in ISO 8601 format (yyyy-mm-dd), e.g., 2019-09-16. +The updated header records the date(s) when the HIP was updated with "substantial" changes. It is only valid for HIPs in `Draft` and `Active` status. This header should be in ISO 8601 format (`yyyy-mm-dd`), e.g., `2019-09-16`. #### `requires` header @@ -331,7 +329,7 @@ HIPs may also have a `superseded-by` header indicating that a HIP has been rende #### `release` header -The `release` header indicates when the HIP was implemented on the network (vX.Y.Z), e.g. `0.29.0`. +The `release` header indicates when the HIP was implemented in the codebase (vX.Y.Z), e.g., `v0.29.0`. ### Linking to other HIPs @@ -349,7 +347,7 @@ When in doubt about where to send your changes, please check first with the HIP ## Transferring HIP Ownership -It occasionally becomes necessary to transfer ownership of HIPs to a new champion. In general, it is preferable to retain the original author as a co-author of the transferred HP, but that's really up to the original author. A good reason to transfer ownership is that the original author no longer has the time or interest in updating it or following through with the HIP process or has fallen off the face of the ‘net. A bad reason to transfer ownership is because the author doesn't agree with the direction of the HIP. One aim of the HIP process is to try to build consensus around a HIP, but if that's not possible, an author can always submit a competing HIP. +It occasionally becomes necessary to transfer ownership of HIPs to a new champion. In general, it is preferable to retain the original author as a co-author of the transferred HIP, but that's really up to the original author. A good reason to transfer ownership is that the original author no longer has the time or interest in updating it or following through with the HIP process or has fallen off the face of the ‘net. A bad reason to transfer ownership is because the author doesn't agree with the direction of the HIP. One aim of the HIP process is to try to build consensus around a HIP, but if that's not possible, an author can always submit a competing HIP. If you are interested in assuming ownership of a HIP, you can also do this via pull request. Fork the HIP repository, make your ownership modification, and submit a pull request. You should mention both the original author and the HIP editors in a comment on the pull request. If the original author doesn't respond in a timely manner, the HIP editors will make a unilateral decision. @@ -363,12 +361,13 @@ For each new HIP that comes in, an editor does the following: If the HIP isn't ready, the editor will send it back to the author for revision with specific instructions. - Once the HIP is ready for the repository, the HIP editor will: +Once the HIP is ready for the repository, the HIP editor will: + - Assign a HIP number (generally the PR number) - Merge the corresponding pull request - Send a message back to the HIP author with the next step. -Editors don't pass judgment on the HIPs. We merely do the administrative & editorial part. + Editors don't pass judgment on the HIPs. We merely do the administrative & editorial part. ## Style Guide