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.
Newest to oldest
- 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
- JSON REST API Rationale and Plan - Aug 2019
- [meta] Design Docs: What are they and how we use them - Aug 2018
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 Communityteam drive,
- Check that you're using the GApps identity of your choice.
IMPLEMENTINGnear 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
firstname.lastname@example.org list, which will reach all committers. Also announce in
#fil-devor 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.