Merge pull request #11 from filecoin-project/fip-spec-integration

FIP process amendment to integrate spec update

Author: momack2

FIPS/fip-0001.md

@@ -16,6 +16,8 @@ FIP stands for Filecoin Improvement Proposal. A FIP is a design document providi
 
 We intend FIPs to be the primary mechanisms for proposing new features, for collecting community technical input on an issue, and for documenting the design decisions that have gone into Filecoin. Because the FIPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal.
 
+However, we also require that, where appropriate, Technical FIPs are also reflected in the protocol's specification, which is the primary source of reference for other developers. The [Filecoin Spec site](https://spec.filecoin.io/) will in turn point back to the FIPs that have changed some part of the protocol, as well as the FIP's revision history.
+
 For Filecoin implementers, FIPs are a convenient way to track the progress of their implementation. Ideally, each implementation maintainer would list the FIPs that they have implemented. This will give end users a convenient way to know the current status of a given implementation or library.
 
 ## FIP Types
@@ -62,7 +64,7 @@ Each status change is requested by the FIP author and reviewed by the FIP editor
   * :arrow_right: Accepted (Core FIPs only) -- A successful Last Call without material changes or unaddressed technical complaints will become Accepted.
   * :arrow_right: Final (Not core FIPs) -- A successful Last Call without material changes or unaddressed technical complaints will become Final.
 * **Accepted (Core FIPs only)** -- This FIP is in the hands of the Filecoin implementation developers.  Their process for deciding whether to encode it into their clients as part of a consensus upgrade is not part of the FIP process.
-  * :arrow_right: Final -- Standards Track Core FIPs must be implemented in at least two viable Filecoin clients before they can be considered Final. When the implementation is complete and adopted by the community, the status will be changed to “Final”.
+  * :arrow_right: Final -- Standards Track Core FIPs must be implemented in at least two viable Filecoin clients before they can be considered Final. A Pull Request to the [Filecoin Specification repository](https://github.com/filecoin-project/specs) updating the text of the spec to describe the protocol changes should also be submitted before the FIP can proceed to the Final status. When the implementation is complete and adopted by the community, the status will be changed to “Final”.
 * **Final** -- This FIP represents the current state-of-the-art. A Final FIP should only be updated to correct errata.
 
 Other exceptional statuses include:
@@ -115,6 +117,10 @@ Each FIP must begin with an RFC 822 style header preamble, preceded and followed
 
 ` created:` \<date created on\>
 
+`spec-sections:` A list of Spec sections that the FIP is updating.
+
+`spec-pr:` The URL for the PR updating the Spec.
+
 ` * updated:` \<comma separated list of dates\>
 
 ` * requires:` \<FIP number(s)\>
@@ -169,6 +175,18 @@ The `category` header specifies the FIP's category. This is required for technic
 
 The `created` header records the date that the FIP was assigned a number. Both headers should be in yyyy-mm-dd format, e.g. 2001-08-14.
 
+#### `spec-sections`
+
+Spec sections that the FIP is updating, each section has an ID that can be found in the Spec website under each section "three dot" menu. Example: https://github.com/filecoin-project/FIPs/pull/11#issuecomment-713435889.
+
+Example:
+```yaml 
+spec-sections:
+  - section-intro
+  - section-libraries.libp2p
+  - section-systems.filecoin_markets.storage_market.deal-flow
+  ```
+
 #### `updated` header
 
 The `updated` header records the date(s) when the FIP was updated with "substantional" changes. This header is only valid for FIPs of Draft and Active status.
@@ -215,6 +233,8 @@ Once the FIP is ready for the repository, the FIP editor will:
 
 - Merge the corresponding pull request
 
+- Check whether the FIP needs to be accompanied by an update to the specification and if so, make sure that a PR to spec repository has been submitted and that the text that updates the spec is reflecting the changes that the FIP proposes.
+
 - Send a message back to the FIP author with the next step.
 
 Many FIPs are written and maintained by developers with write access to the Filecoin codebase. The FIP editors monitor FIP changes, and correct any structure, grammar, spelling, or markup mistakes we see.

README.md

@@ -28,7 +28,7 @@ When making decisions about how to improve Filecoin, we will follow a set of pri
 
 FIPs are classified into three categories:
 
-**Technical FIPs, or Filecoin Technical Proposals (FTPs)** are designed to gather community feedback on technical Filecoin issues. These include changes to the Filecoin protocol, a change in block or transaction validity rules, and proposed application standards or conventions. They are then reviewed by the Filecoin community and the technical steering committee.
+**Technical FIPs, or Filecoin Technical Proposals (FTPs)** are designed to gather community feedback on technical Filecoin issues. These include changes to the Filecoin protocol, a change in block or transaction validity rules, and proposed application standards or conventions. They are then reviewed by the Filecoin community and the technical steering committee. They are normally followed by a PR to the [Filecoin Specification repository](https://github.com/filecoin-project/specs) to update the protocol's spec.
 
 **Organizational FIPs, or Filecoin Organization Proposals (FOPs)** allow the Filecoin community to propose, discuss, and achieve consensus on Filecoin governance. This includes procedures, guidelines, decision-making processes, and changes to FIP processes.
 

templates/template_FTP.md

@@ -7,6 +7,9 @@ status: Draft
 type: <Technical (Core, Networking, Interface, Informational)  | Organizational | Recovery>
 category (*only required for Standard Track): <Core | Networking | Interface >
 created: <date created on, in ISO 8601 (yyyy-mm-dd) format>
+spec-sections: 
+  - <section-id>
+  - <section-id>
 requires (*optional): <FIP number(s)>
 replaces (*optional): <FIP number(s)>
 ---

writing_FIPs.md

@@ -7,16 +7,19 @@ Filecoin Improvement Proposals (FIPs) describe standards for the Filecoin platfo
  2. Fork the repository by clicking "Fork" in the top right.
  3. Add your FIP to your fork of the repository. There are [template FIPs here](/templates).
  4. Submit a Pull Request to Filecoin's [FIPs repository](https://github.com/filecoin-project/FIPs).
+ 5. Draft and submit a Pull Request to the [Filecoin Specification repository](https://github.com/filecoin-project/specs) to update the spec with the changes that your FIP brings.
 
 Your first PR should be a first draft of the final FIP. It must meet the formatting criteria enforced by the build (largely, correct metadata in the header). An editor will manually review the first PR for a new FIP and assign it a number before merging it. Make sure you include a `discussions-to` header with the URL to a discussion forum or open GitHub issue where people can discuss the FIP as a whole.
 
 If your FIP requires images, the image files should be included in a subdirectory of the `assets` folder for that FIP as follow: `assets/fip-X` (for fip **X**). When linking to an image in the FIP, use relative links such as `../assets/fip-X/image.png`.
 
-Once your first PR is merged, we have a bot that helps out by automatically merging PRs to draft FIPs. For this to work, it has to be able to tell that you own the draft being edited. Make sure that the 'author' line of your FIP contains either your Github username or your email address inside <triangular brackets>. If you use your email address, that address must be the one publicly shown on [your GitHub profile](https://github.com/settings/profile).
+Once your first PR is merged, we have a bot that helps out by automatically merging PRs to draft FIPs. For this to work, it has to be able to tell that you own the draft being edited. Make sure that the 'author' line of your FIP contains either your Github username or your email address inside `<triangular brackets>`. If you use your email address, that address must be the one publicly shown on [your GitHub profile](https://github.com/settings/profile).
 
 When you believe your FIP is mature and ready to progress past the draft phase, you should do one of two things:
 
- - **For a Standards Track FIP of type Core**, ask to have your issue added to [the agenda of an upcoming All Core Devs meeting](https://github.com/filecoin-project/tpm/issues), where it can be discussed for inclusion in a future chain upgrade. If implementers agree to include it, the FIP editors will update the state of your FIP to 'Accepted'.
+ - **For a Standards Track FIP of type Core**:
+ 	- ask to have your issue added to [the agenda of an upcoming All Core Devs meeting](https://github.com/filecoin-project/tpm/issues), where it can be discussed for inclusion in a future chain upgrade. If implementers agree to include it, the FIP editors will update the state of your FIP to 'Accepted'.
+ 	- prepare the changes to the spec text necessary to describe the protocol modifications that your FIP brings. Submit a PR to the [Filecoin Specification repository](https://github.com/filecoin-project/specs). These changes will also be discussed in the "All Core Devs" meeting and the editor will assign a reviewer.
  - **For all other FIPs**, open a PR changing the state of your FIP to 'Final'. An editor will review your draft and ask if anyone objects to its being finalised. If the editor decides there is no rough consensus - for instance, because contributors point out significant issues with the FIP - they may close the PR and request that you fix the issues in the draft before trying again.
 
 # FIP Status Terms