Design Docs

This README is an index of documents for important components and changes, as well as notes, thoughts, and discussions that don't fit anywhere else yet.

See Design Docs: What are they and how we use them.

Design Docs

Newest to oldest

• Filecoin Chain-Validation Tools - November 2019
• Filecoin component architecture - October 2019
• Go-filecoin code layout - September 2019
• JSON REST API Rationale and Plan - Aug 2019
• Protocol Upgrade Table - July 2019
• Hello Protocol and Protocol Versions - July 2019
• Separating Messages from Block July 2019
• Faults & Slashing implementation - June 2019
• SectorSet and Bitfield Implementation Plan - June 2019
• Model for change: Filesystem repo migrations - April 2019
• Slashing Mechanism - March 2019
• Outbound Message Queue - March 2019
• Message Tracking - Feb 2019
• Porcelain/Plumbing Refactor Plan - Feb 2019
• [meta] Design Docs: What are they and how we use them - Aug 2018

Video Recordings

Explainer talks or demos.

Other Writeups & Notes

Other writeups or less-edited notes from discussions & meetings

• Are We Speced Yet?

How to Create New Design Docs

We follow a process to ensure that new design docs are accessible and communicated widely.

• Create a GitHub issue for the design doc in the appropriate repository (e.g. go-filecoin, consensus).
• Create a new Google doc in the Filecoin Community team drive, Design Docs folder.
  • Check that you're using the GApps identity of your choice.
  • Use DRAFT, IN REVIEW, IMPLEMENTING near the top of the content to note status.
• When you're ready, enable public comments. As of April 2019, this takes 5 clicks:
  • Click "Share" button.
  • Click "Who has access" to open the advanced settings panel.
  • Toggle on "Link sharing".
  • Choose who: "Anyone with the link".
  • In the dropdown after "Access", select "Can comment".
• Add an entry with shareable link in this README's list of design docs, thus making the document public (you can commit directly).
• Email a link to the [email protected] email list, which will reach all committers. Also announce in #fil-dev or other appropriate channel the filecoin-project Slack.
  • This email thread will function as a low-noise channel for high-level discussion of the proposal.
• Solicit feedback from individuals and/or channels, evolving the design as needed.
  • Advertise major changes with a post to the email/slack threads where the design was announced.
  • Seek approval from at least one maintainer before considering the proposal accepted.
• Once ready, translate into GitHub/ZenHub epics or issues according to the appropriate repo's contributing guide.

Note: people outside committers and some other full-time project contributors cannot directly place docs in the team drive. If a document originates outside this set but is accepted, a committer should copy the content into the team drive.

As an alternative to Google Drive, a design doc may be drafted in a PR to a markdown file in the docs directory of this repository.

Contributing to this repo

We play fast and loose in this here designdocs repo, but not recklessly.

• If you are adding new content, committers can commit directly.
• If you are editing or refactoring existing content, get 1 reviewer (preferably the original author, but others if they're not available). If they don't reply in 3 days with reasonable reminding efforts, committers can commit directly.