Professionalism and focus, win-win cooperation Over the past few months, the development team has made tremendous progress in revising the Filecoin spec and its custom website! There have been countless updates, making the spec more than 6 times more accurate than before, achieving an 85% completeness score, and many other details are already in progress. Status tagging, searching the spec, and many other aspects have been significantly improved due to the new workflow. If you haven’t visited the Filecoin Spec site recently, please go to: https://spec.filecoin.io/ to see a completely revamped site with updated content! The Spec site has gone through several rounds of "Design → Implementation → Deployment" to incorporate all the features that Filecoin developers, implementers, researchers, and ecosystem developers need to create an excellent platform. In addition, we reduced the complexity required to update specification content, applied structured dependency management, added features to ensure consistency across the specification, added support for new tools, and more! New Filecoin specification contribution workflow Now, updating the spec content has become much easier and more fun, involving a "one-touch" edit in the markdown file. The backend mechanism takes care of the rest and automatically updates the Table of Contents (ToC) and the document structure! You can find all the simple instructions you need to contribute to the spec's repo README file. The most noteworthy features of the updated site fall into the following categories: Seamlessly control dependencies with npm and Go modules Seamless math support via Katex New markdown, with some custom rules to ensure consistency in markdown for content, which is run as a test in CI.
2. Figures and code blocks The Mermaid and Dot processing pipelines (with the option to add more in the future) integrate well with the Hugo server for development and content editing. Code can be referenced from the specification using symbolic shortcodes so that even if the codebase itself is modified, the correct code block can be referenced and pulled from the corresponding repository.
Extract section numbers from the ToC so that the ToC is automatically updated after reorganizing sections. No need to edit separate files to keep them in sync. Deep link integration. Single page rendering is now stable and reflects the section structure in the ToC.
In addition to these background changes, the website has also received a revamp! In terms of content, we’ve put a lot of effort into updating the protocol description. Filecoin is a huge project. To put it in perspective, if it were printed, the protocol specification would be a textbook of about 400 pages ! The Filecoin specification is implementation-agnostic, meaning that the text describes the algorithms and protocol interactions that make the network work well without going into implementation details. The specification provides all the required details that developers need to implement Filecoin in any language. References to the Lotus implementation are only provided when needed. During the 3-month Spec Project, more than 300 GitHub issues were opened and more than 200 PRs were merged. Today, the canonical site is 84% updated. To track our own progress and the “health” of the site and the protocol, we combined three great tools: Bright Dashboard: Shows the status of each section of the specification with a range of "Incorrect", "WIP/Draft", "Reliable", and "Stable". We integrated front-end material properties in the spec markdown file to automatically input these values into the dashboard without you having to do anything else. It's also worth noting that the dashboard is automatically generated and updated from the ToC. No need to edit a separate file to update the dashboard! "Audit Complete" indicator: as a separate column on the dashboard to show whether a specific component of the agreement has been audited. If there is an audit report, there is a link to that report (or a list of previous reports) and the date the audit was conducted. 1. A steady progress bar that summarizes the status of the entire specification. 2. A separate “Implementation Status” dashboard. It contains status information for all the different Filecoin implementations: Lotus, Fuhon, Forest, and go-filecoin. The dashboard integrates hooks to seamlessly pull information from the corresponding repositories and reports CI test success/failure and test coverage. After several rounds of testing and two impressive space races, the protocol is now fine-tuned and ready for implementation! From now on, changes to the protocol will be made through Filecoin Improvement Proposals (FIPs). Proposed changes to the protocol must go through a clearly specified process, which is detailed in the FIP repository. In most cases, FIPs will require updates to the protocol spec, so part of our ongoing work includes seamlessly integrating the Filecoin Spec with the FIP process. We are also integrating with specification versioning to create a Time Machine of the specification itself so that you can view the specification in time before the protocol was updated. Last but not least, we are integrating tools to pull data from remote sources via an API proxy. This will enable seamless integration with FIPs, but will also allow us to expand the dashboard to include the status of "Conformance Testing". If you are a Filecoin developer, researcher, on-chain node, or user, we would love to: The protocol and its specs have made significant progress and upgrades over the two rounds of Space Race, so now it’s time to put more effort into getting all of Filecoin’s spec dashboard cells painted blue! We plan to have 90% solid content in the next few weeks and 100% stable content in the following months. |
