Skip to content
Docs that capture the design intent for important components
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

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

Video Recordings

Explainer talks or demos.

Other Writeups & Notes

Other writeups or less-edited notes from discussions & meetings

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 dev@filecoin.org 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.
You can’t perform that action at this time.