diff --git a/.github/workflows/specs-deploy.yml b/.github/workflows/specs-deploy.yml new file mode 100644 index 00000000..ab0ab5ff --- /dev/null +++ b/.github/workflows/specs-deploy.yml @@ -0,0 +1,47 @@ +name: Specs Deploy + +on: + push: + branches: + - main + paths: + - specs/** + pull_request: + paths: + - specs/** + workflow_dispatch: + +jobs: + deploy: + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + steps: + - uses: actions/checkout@v4 + + - name: Setup mdBook + uses: peaceiris/actions-mdbook@v1 + with: + mdbook-version: "0.4.21" + + - name: Build book + run: mdbook build specs + + - name: Deploy main + if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./specs/book + # keep_files is to prevent PR preview files from being overwritten. + # If we need to overwrite such files, trigger this workflow manually. + keep_files: ${{ github.event_name != 'workflow_dispatch' }} + + - name: Deploy PR preview + # Only run this job if the PR was created from a branch on + # rollkit/rollkit because this job will fail for branches from forks. + if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository + uses: rossjrw/pr-preview-action@v1 + with: + source-dir: ./specs/book diff --git a/p2p/p2p.md b/p2p/p2p.md new file mode 100644 index 00000000..e69de29b diff --git a/specs/.gitignore b/specs/.gitignore new file mode 100644 index 00000000..7585238e --- /dev/null +++ b/specs/.gitignore @@ -0,0 +1 @@ +book diff --git a/specs/README.md b/specs/README.md new file mode 100644 index 00000000..c54d0af0 --- /dev/null +++ b/specs/README.md @@ -0,0 +1,38 @@ +# go-header Specifications + +## Building From Source + +Install [mdbook](https://rust-lang.github.io/mdBook/guide/installation.html) and [mdbook-toc](https://github.com/badboy/mdbook-toc): + +```sh +cargo install mdbook +cargo install mdbook-toc +``` + +To build book: + +```sh +mdbook build +``` + +To serve locally: + +```sh +mdbook serve +``` + +## Contributing + +Specifications are written and stored in the same directory with the implementation code. Since `mdbook` does not support referencing files outside of the book directory, we use a symlink to the `src/specs` directory. This allows us to reference the specifications from the `README.md` and `SUMMARY.md` files in the `src` directory. + +To create a symlink: + +```sh +cd src/specs +ln -s path/to/spec.md +``` + +Markdown files must conform to [GitHub Flavored Markdown](https://github.github.com/gfm/). Markdown must be formatted with: + +- [markdownlint](https://github.com/DavidAnson/markdownlint) +- [Markdown Table Prettifier](https://github.com/darkriszty/MarkdownTablePrettify-VSCodeExt) diff --git a/specs/book.toml b/specs/book.toml new file mode 100644 index 00000000..afb11daf --- /dev/null +++ b/specs/book.toml @@ -0,0 +1,16 @@ +[book] +authors = ["Celestia Labs"] +language = "en" +multilingual = false +src = "src" +title = "go-header Specifications" + +[output.html] +git-repository-url = "https://github.com/celestiaorg/go-header" + +[rust] +edition = "2021" + +[preprocessor.toc] +command = "mdbook-toc" +renderer = ["html"] diff --git a/specs/src/README.md b/specs/src/README.md new file mode 100644 index 00000000..fea080d0 --- /dev/null +++ b/specs/src/README.md @@ -0,0 +1,3 @@ +# Welcome + +Welcome to the go-header Specifications. diff --git a/specs/src/SUMMARY.md b/specs/src/SUMMARY.md new file mode 100644 index 00000000..2b705a6d --- /dev/null +++ b/specs/src/SUMMARY.md @@ -0,0 +1,8 @@ +# Summary + +[Introduction](README.md) + +- [Template](./specs/template.md) +- [P2P](./specs/p2p.md) +- [Store](./specs/store.md) +- [Sync](./specs/sync.md) diff --git a/specs/src/specs/p2p.md b/specs/src/specs/p2p.md new file mode 120000 index 00000000..e3200124 --- /dev/null +++ b/specs/src/specs/p2p.md @@ -0,0 +1 @@ +../../../p2p/p2p.md \ No newline at end of file diff --git a/specs/src/specs/store.md b/specs/src/specs/store.md new file mode 120000 index 00000000..ccf6f0ce --- /dev/null +++ b/specs/src/specs/store.md @@ -0,0 +1 @@ +../../../store/store.md \ No newline at end of file diff --git a/specs/src/specs/sync.md b/specs/src/specs/sync.md new file mode 120000 index 00000000..31a89e3d --- /dev/null +++ b/specs/src/specs/sync.md @@ -0,0 +1 @@ +../../../sync/sync.md \ No newline at end of file diff --git a/specs/src/specs/template.md b/specs/src/specs/template.md new file mode 120000 index 00000000..35b615ac --- /dev/null +++ b/specs/src/specs/template.md @@ -0,0 +1 @@ +../../template.md \ No newline at end of file diff --git a/specs/template.html b/specs/template.html new file mode 100644 index 00000000..8e669a5d --- /dev/null +++ b/specs/template.html @@ -0,0 +1,448 @@ + + + + + + Template - go-header Specifications + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + + + + +
+
+ + + + + + + + +
+
+

+ Protocol/Component Name +

+

+ Abstract +

+

+ Provide a concise description of the purpose of the component + for which the specification is written, along with its + contribution to the celestia-app or other relevant parts of the + system. Make sure to include proper references to the relevant + sections. +

+

+ Protocol/Component Description +

+

+ Offer a comprehensive explanation of the protocol, covering + aspects such as data flow, communication mechanisms, and any + other details necessary for understanding the inner workings of + this component. +

+

+ Message Structure/Communication Format +

+

+ If this particular component is expected to communicate over the + network, outline the structure of the message protocol, + including details such as field interpretation, message format, + and any other relevant information. +

+

+ Assumptions and Considerations +

+

+ If there are any assumptions required for the component's + correct operation, performance, security, or other expected + features, outline them here. Additionally, provide any relevant + considerations related to security or other concerns. +

+

+ Implementation +

+

+ Include a link to the location where the implementation of this + protocol can be found. Note that specific implementation details + should be documented in the core-app repository rather than in + the specification document. +

+

+ References +

+

List any references used or cited in the document.

+
+ + +
+
+ + +
+ + + + + + + + + + + + + + + +
+ + diff --git a/specs/template.md b/specs/template.md new file mode 100644 index 00000000..3f70a113 --- /dev/null +++ b/specs/template.md @@ -0,0 +1,37 @@ +# Protocol/Component Name + +## Abstract + +Provide a concise description of the purpose of the component for which the +specification is written, along with its contribution to the go-header or +other relevant parts of the system. Make sure to include proper references to +the relevant sections. + +## Protocol/Component Description + +Offer a comprehensive explanation of the protocol, covering aspects such as data +flow, communication mechanisms, and any other details necessary for +understanding the inner workings of this component. + +## Message Structure/Communication Format + +If this particular component is expected to communicate over the network, +outline the structure of the message protocol, including details such as field +interpretation, message format, and any other relevant information. + +## Assumptions and Considerations + +If there are any assumptions required for the component's correct operation, +performance, security, or other expected features, outline them here. +Additionally, provide any relevant considerations related to security or other +concerns. + +## Implementation + +Include a link to the location where the implementation of this protocol can be +found. Note that specific implementation details should be documented in the +go-header repository rather than in the specification document. + +## References + +List any references used or cited in the document. diff --git a/store/store.md b/store/store.md new file mode 100644 index 00000000..e69de29b diff --git a/sync/sync.md b/sync/sync.md new file mode 100644 index 00000000..e69de29b